PRO/Tool Kit 
Command Language 
and Utilities Manual 


Order No. AA-X912B-TH 


November 1985 


This manual describes the Command Language and utilities 
provided with the PRO/Tool Kit. It is a detailed 
reference manual for programmers. 


REQUIRED SOFTWARE: Hosi Tool Kit V3.0, 
or PRO/Tool Kit V3.0 


OPERATING SYSTEM: P/OS V3.0 


allo} ital 


DIGITAL EQUIPMENT CORPORATION 
Maynard. Massachusetts 01754-2571 


First Printing, September 1983 
Revised November 1985 


The information in this document is subject to change without 
notice and should not be construed as a commitment by Digital 
Equipment Corporation. Digital Equipment Corporation assumes no 
responsibility for any errors that may appear in this document. 


The software described in this document is furnished under a 
license and may only be used or copied in accordance with the 
terms of such license. 


No responsibility 1s assumed for the use or reliability of 
software on equipment that is not supplied by DIGITAL or its 
affiliated companies. 


The specifications and drawings, herein, are the property of 
Digital Equipment Corporation and shall not be reproduced or 
copied or used in whole or in part as the basis for the 
manufacture or sale of items without written permission. 


Copyright© 1985 by Digital Equipment Corporation 
All Rights Reserved 


The following are trademarks of Digital Equipment Corporation: 


CTT BUS MASSBUS Rainbow 
DEC PDP Rolls 
DECmate P/OS RSX 
DECsystem-10 PRO/BASIC Tool, Kit 
DECSYSTEM-20 PRO/Communications UNIBUS 
DECUS Professional VAX 
DECwriter PRO/FMS VMS 
DIBOL PRO/RMS ve 


lilo} i| tal | il PROSE Work Processor 


PROSE “PLUS 


CONTENTS 


PREFACE a. 8. SE Ge sae Gr ie ee woe. 2 & & & & MTT 
CHAPTER 1 INTRODUCTION 
A eee PRO/TOOL KIT DCL : ie 
se re | File/Device/Volume Manipulation Commands 1-2 
se Sore? Program Development Commands ca we ae see 
5 ees lire: Task Manipulation Commands ........ 1-2 
pres ae | Set and Show Commands 1-3 
Cee SS Miscellaneous Commands 1-3 
Lae PRO/TOOL KIT UTILITIES a ee eee 1-3 
Be hh eck Program Development, Frame, and Form 
Utilities eo. we. te a oe Oe ee ee 
5 eee Ame RMS; UGCLAT CIES sw ww. S.-o. 8 ue: ee ee a wc ae e & SSO 
Ledie3 Other Utilities 1-7 
CHAPTER 2 USING PRO/TOOL KIT DCL 
ot THE DCL COMMAND LINE 2-1 
cre ares Prompting 2-2 
2.1.2 Qualifiers 2-3 
Pe ae: HELP eh 2-5 
2 vikiacd Abbreviations | 
py) ares. Colon and Equal Sign 2-1 
Ls wO Command Line Continuation 2-8 
an awa | Comments in Command Lines 2-8 
228 Errors 2-9 
J2ebe9 PRO/Tool ree DCL ee er ee ana. 
Termination Files .. 2-10 
Zed CORRECTING MISTAKES WITH THE DCL SINGLE LINE 
EDITOR: :4- ¢ 7 a ee en ee ee 
2.3 P/OS FILE SPECIFICATIONS IN. DCL” i we. we ac ee & Beds 
25338 Wildcard Features in DCL ......... 24-13 
Lie Bee Logical Name Translation . . x @. wi. or oS 
2.4 FOREGROUND AND BACKGROUND PROCESSING ee 
Dra ci dk SCTREy Co & te Gs oi tae KO oe ae te we Oe ee 
Di Bad BOORT % w..%. & @ ow & Ge we & a & ee Sek ew Se 
CHAPTER 3 DCL COMMANDS 
oie ABORT S- ate +e Cat. SE. CA S. don: We ae “de a 3-2 
Ce APPEND <4 ¢ 2 «=~ < & Gc’. € as 24. S & SB aw 2. BH4 
345 ASSIGN 3-8 
3.4 ASSIGN/TASK 3-12 
S20 BASIC 3-13 


aie 


WWW WW WWW Ww WW WWW Ww Ww WWW Ww WW WW Ww Ww Ww Dw Dw Ww WD WD WD Dw Dw De Ww WD Ww Ww De Ww wD a De we Ww wa we w 
@ @ @ eo e@ #6 6 e® ee  @  @ 6 e ® @®  @  @  @®@ @  @ @ @®@ @® @®@ @ @®  @® @®  @ 6 nn) o # ®6 so ses e 6 e 


CANCEL 

CLEAR 

COBOL 

CONTINUE 
CONVERT 

COPY 

CREATE a 
CREATE/DIRECTORY 
DEASSIGN 

DEBUG 

DEFINE 

DELETE — 
DELETE /DIRECTORY 
DIBOL Be ii 
DIFFERENCES 
DIRECTORY 
DISMOUNT 

DUMP oe 
EDIT OR EDIT/EDT 
EDIT/PROSE 
EDIT/SLP 

EXIT 

FIX 

FORMAT 

FORTRAN 

HELP 
INITIALIZE 
INSTALL 

LIBRARY — 
LIBRARY/COMPRESS 
LIBRARY/CREATE 
LIBRARY/DELETE 
LIBRARY /EXTRACT 
LIBRARY/INSERT 
LIBRARY/LIST 
LIBRARY /REMOVE 
LIBRARY/REPLACE 
LINK se 
LINK/C81 

LOAD 

MACRO 

MAIL 

MOUNT 

PASCAL 

PHONE 

PRINT 
PRINT/REMOTE 
PURGE 

REMOVE 

RENAME 


RUN uninstalled task 


1V 


3-14 
3-15 
3-16 
3-23 
3-24 
3-30 
2337 
3-40 
3-42 
3-44 
3-45 
3-49 
3-52 
3>53 
aL 
3-61 
3-65 
3-66 
5272 
3-74 
225 
3-78 
S279 
3=81. 
3-82 
3-88 
3=69 
3291 
5293 
3-94 
3-96 
3=99 


3-100 


3-101 
3-103 
3=105 
3-106 
3-108 
a 23 
32126 
3-127 
3-135 
3+ 136 
be rs 
3-140 
3-141 
3-142 
3-143 
3-146 
3-147 
3-150 


CHAPTER 


= 


> > 


WWW Ww WwW WwW WWW WW Ww WWW WwW WwW WW DW WW WW WW WD Dw Ze WD WD WD LD 
eo @e@# @®@ @® @®  @  @  @ eo es @® @ ®@ @ eo 8 @ @®@ @®  @  @®  @  @  @  @®  @  @o@ #4@ 


Dm PP S&P Ph Pb 
t) e e e 8 ® @ 6 @ @ 
Dm > PP SP PP PWD PF 


> 


WNPPRPPR 


Ww DN Fk 


RUN 
SET 
SET 
SET 
SET 
SET 
SET 
SET 
SET 
SET 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 
SHOW 


installed task 

[DAY ]TIME 

DEFAULT 

DEVICE 

HOST 

PRIORITY 

PROTECTION : 
PROTECTION/DEFAULT 
PROTECTION/NODEFAULT 
TERMINAL o> 2a 
ASSIGNMENTS 
CLOCK_QUEUE 

COMMON r 
DAYTIME or SHOW TIME 
DEFAULT 

DEVICES 

LOGICALS 

MEMORY 

PROTECTION 
TASKS/ACTIVE 

TASKS /INSTALLED 
TASK: taskname/DYNAMIC 
TASKS /ACTIVE/DYNAMIC 
TASK/LOGICAL UNITS 
TERMINAL i 


5 PAWN 


STAR 
STAR 


T 
T/UNBLOCK | 


STOP /BLOCK 


SUBM 
a 


IT/REMOTE 


UNLOAD 


UNLO 


THE 


INDI 
INDI 


CK 


INDIRECT COMMAND PROCESSOR 


RECT COMMAND FILES 
RECT COMMAND PROCESSOR 


SUMMARY OF INDIRECT DIRECTIVES 


SYMB 


OLS 


Special Syiibols 


Special Logical Symbols 
Special Numeric Symbols 
Special String Symbols 


Numeric Symbols and Expressions 


String Symbols, 
Expressions 


Substrings, and 


Reserved Symbols 
Symbol Value suosecuton: 


Substitution Format Control 


| 
DN S&F WOOO OO FN PF 


a 
| 
> 
CO 


> 


> PP PP LS 
WO CO ~) OW WN 


mam > Pm & 
Ce 2 


mee Ph HL LP LS 
e e ¢- ee 6 


~~ Pb bb & 
¢«- oe  @ 


Cn SS SY SO SO OT 
© bd e ° e e e e 


SWITCHES : d 
Using Indirect pireceryes 
Logical Tests 

/ ~ DEFINE LOGICAL END- OF- FILE 

-ASK - ASK A QUESTION AND WAIT FOR A REPLY 
-ASKN - ASK FOR DEFINITION OF A NUMERIC 
SYMBOL 
-ASKS 
SYMBOL 
sBEGIN: = BEGIN BLOCK 

-CHAIN - CONTINUE PROCESSING USING ANOTHER 
FILE 

sCLOSE = CLOSE SECONDARY FILE. : 

-DATA - OUTPUT DATA TO SECONDARY FILE 

-DEC - DECREMENT NUMERIC SYMBOL 

.DELAY - DELAY EXECUTION FOR A SPECIFIED 
PERIOD OF TIME 

-DISABLE - DISABLE OPTION 

-ENABLE - ENABLE OPTION 

-END - END BLOCK 

-ERASE - DELETE SYMBOLS 

~EXIT - EXIT CURRENT COMMAND FILE 

-FORM - ACCESS FORM DRIVER 

-GOSUB - CALL A SUBROUTINE 

-GOTO - BRANCH TO A LABEL 

-IF - TEST IF SYMBOL SATISFIES SPECIFIED 
CONDITION ee ee a ee ee ee ee 
~IFACT/.IFNACT - TEST IF TASK IS ACTIVE OR 
DORMANT 


- ASK FOR DEFINITION OF A STRING 


~IFDF/.IFNDF - TEST IF SYMBOL DEFINED OR NOT 


DEFINED 
eLFINS/.IFNINS 
NOT INSTALLED he BL ey, ew 
. [FENABLED/. IFDISABLED - TEST IF MODE 
ENABLED OR DISABLED 


- TEST IF TASK INSTALLED OR 


~IFLOA/.IFNLO - TEST IF DRIVER LOADED “OR NOT 


LOADED gag tee fame cee Z, &. @. Ge ce ooh 
.IFT/.IFF - TEST IF SYMBOL TRUE OR FALSE 
.INC - INCREMENT NUMERIC SYMBOL : 
.label: - DEFINE A LABEL 

.ONERR - BRANCH TO LABEL ON DETECTING AN 
ERROR 

.OPEN - OPEN SECONDARY FILE 

.OPENA - OPEN SECONDARY FILE FOR APPEND 
.OPENR - OPEN FILE FOR READING 

.PARSE - PARSE STRINGS INTO SUBSTRINGS 
.PAUSE - PAUSE FOR OPERATOR ACTION 

.READ - READ NEXT RECORD 

.RETURN - RETURN FROM A SUBROUTINE : 
.SETT/.SETF/.SETL - SET SYMBOL TO TRUE OR 
FALSE 


CHAPTER 


CHAPTER 


CHAPTER 


mh me PhP PhP hhh Hh LP 


ma > 


OV eR) 


~J 


Wm On Oo OF OF OF OT UO} 


Gv OV OV OV OV OV OV OD 


Jy ~ 
NPPPRP PR 


43 
44 
45 
46 
47 
48 
49 
20 
ol 
“wo 
223 
24 
Mees 


. 96 
Ora 
02 


Ol & SP SP PWN FP 
SS 


Ol & PSP Se HB WN FP 
bo kr 


BONN FR 


DO ke 


-SETN - SET SYMBOL TO NUMERIC VALUE 
-SETO/.SETD - SET SYMBOL TO OCTAL OR DECIMAL 
-SETS - SET SYMBOL TO STRING VALUE : 
-STOP - TERMINATE COMMAND FILE PROCESSING 


-TEST - TEST SYMBOL 
sTESTDEVICE = TEST DEVICE 
~TESTFILE = TEST A FILE 
«LT ESTPARTITION 
JI BSTSOYSTEM. = TEol sSYorTEM 


. TRANSLATE - TRANSLATE A LOGICAL NAME 

.WAIT - WAIT FOR A TASK TO FINISH EXECUTION 
-XQT - INITIATE PARALLEL TASK EXECUTION 
COMPATIBILITY WITH COMMAND FILES FROM RSX 


SYSTEMS 
INDIRECT MESSAGES” 


Information-Only Messages 


Error Messages 


FILE COMPARE UTILITY (CMP) 


INVOKING CMP 
CMP COMMAND FORMAT 
CMP SWITCHES © 


FORMATS ‘OF CMP OUTPUT FILES 


Differences Format 

Change Bar Format 

SLP Command Input Format 
CMP MESSAGES S. ee oe 


FILE DUMP UTILITY (DMP) 


INVOKING DMP 

DMP COMMAND FORMAT 

DMP SWITCHES 

DMP EXAMPLES P 
A Multiple Format Dung 
A Record Dump 
A Header Dump 

DMP ERROR MESSAGES 


LIBRARIAN UTILITY PROGRAM (LBR) 


FORMAT OF LIBRARY FILES 
Library Header 
Entry Point Table 
Module Name Table 
Module Header 
LBR RESTRICTIONS 


Vil 


= TEor A PARTITION 


4-78 
4-79 
4-80 
4-82 
4-83 
4-85 
4-86 
4-87 
4-88 
4-90 
4-91 
4-92 


4-93 
4-94 
4-94 
4-95 


mm om Oo WM UF UI OF UI 
, 
WO CO On~AI AW DY NH 


1 ODN OA OV OV OV 
ei. 4 I 
Pow wo OWN NM 


OV OV 


CHAPTER 


~] 


~] ~] 


Io yr ~aasa ~~) 


Co €& © CO CO WO WO © 


CC WO © 


Ooo moon 


mmm wa os oo ee we 


mm Mm WhO NHN FF FP JIAYAYVN UM 


NDNMOUM UW 


OnyN MN S&S WD 


mM > & 


Ce) 


ae 
NF Oo 


Hm W HN FR 


INVOKING LBR 

DEFAULTS FOR LBR FILE. SPECIFIERS 

LBR SWITCHES a ee ee 
Compress Switch (/CO) 
Create Switch (/CR) 
Delete Switch (/DE) 
Default Switch (/DF) 
Delete Global Switch (/DG) 
Entry Point Switch 7 /7eP) 
Extract). Switch (0/EX) 
Insert Switch (/IN) 
Libraries | 
Insert Switch 
Libraries a 
List Switches (/LI, 
Modify Header Switch 


for Object and Macro 
(/IN) for Universal 
J/LE, /FU) 
(/MH ) 


Replace Switch (/RP) For Macro ead Bbyect, 
Libraries a a ae 

Replace Switch (/RP) cor Gaemesl 
Libraries 


Selective Scanch switch. 
Squeeze Switch (/SZ) 
COMBINING LIBRARY FUNCTIONS 
LBR ERROR MESSAGES : 
Effect of Fatal Errors on ‘hiprery Pides. 
LBR. Brror Messages t pe we, 4 i vere 


(/SS) 


RESOURCE MONITORING DISPLAY (RMD) 


INTRODUCTION 
Display Pages 
setup Pages 
INVOKING RMD 
Running RMD on a Second “Terminal 
THE HELP DISPLAY 
THE MEMORY DISPLAY ; 
Altering the Memory bidnlay From the Setup 
Page i os ae Oe. em te A 
The FREE coma 
The RATE Command 
THE ACTIVE TASK DISPLAY 
Altering the Active Task Display enon: the 
Setup Page bs -ia oe, 38 a, SR EE 28 
The OWNER command 
The PRIORITY Command 
The RATE Command 
The TASK Command 
THE TASK HEADER DISPLAY 
Altering the Task Header Display Oeil. the 
setup Page ee . 


Vit 


Oa Ou The RATE ‘Command 2» 4 «~ 4.4 6 & &@« « « BeL2 
OO 16:2 Ene TASK: COMManG ec: S. 4: <05 as. 4: wt de He. & & BST 
O57) BRROR MESOAGES: <<. =. c: “8 & 6. @ 2. “rw eB. ee 2 ea 
CHAPTER 9 TASK/FILE PATCH PROGRAM (ZAP) 
eet ZAP OPERATING MODES AND SWITCHES . .«.« «% 4 9-2 
Sees ee The List Switch (/LI) 9-3 
Os ede ch The /LI Switch and Regular Task image 
Files .. 9-3 
oe aes Ree The /LI Syrceh wa heeecer Task mage: 
Files 9-4 
Se ee ee The /LI ey aa. pestdene: Leprane se 9-4 
Os The /LI Switch and I- and D-Space Tasks 9-5 
G22 ADDRESSING LOCATIONS IN FILES ‘ 9-5 
Ocak Relocation Biases a) 
Cela e ZAP Addressing Modes : 9-5 
ae ee Aes Using the Task Image Addressing “Mode - 9-7 
Da erik Using the Absolute Addressing Mode 9-7 
- INVOKING AND TERMINATING ZAP 9-7 
eae ees Using Indirect Command Files Waren. ZAP 9-8 
G4 THE ZAP COMMAND LINE AND COMMAND LINE 
ELEMENTS gs ee a ea a ete GS we te ee ek Se | ES 
DO eiatind: ZAP Commands .... yk. ek pe ee SD 
= ee! are ieee Open/Close Location Commands 9~-9 
2 ee a General Purpose Commands 9-10 
ee eee ee <RETURN> Key Sf Sw & Be oo ae ae ee Dede 
98 22 ZAP Internal Registers i oh Bae Oe, ce. ee 
= ae a ZAP Arithmetic Operators .. . ot: ay et 
9.4.4 ZAP Command Line Element Separators ey ep DoeL2 
ae ee: ZAP Command Line Location- center 
FOrMats: «< « « a a en a 
oe | eo eae | The Current HoeaeOn Symbol. Ge 1. Gh. See ter ce ee 
Dla DZ Byte Offset Format .. ; 5 ee @ DTS 
Cre ares em Block Number: Byte Offset Format ee . 9-13 
9 4.84 Relocation Register, Byte Offset Bernice 9-14 
95 USING ZAP OPEN AND CLOSE COMMANDS .... . 9-14 
Shoe | Opening Locations ina File «2. «1 « « » « » 9=16 
res weer Changing the Contents: of a Location = «a. 9-16 
oes Closing Locations ina File .. s GeLT 
Stes eae gee Closing a Location and opening the 
Preceding Location 4g fe a eed? 
eee re ee Closing a Location and opening an 
Offset Location .. a3 &. Dele 
es eee ee) Closing a Location and Opening an 
Absolute Location .. é 2 a be OSES 
Je 525-24 Closing a Location er opening a 
Branch Target Location... wy 2k Se SPSL 
ores ie es Closing a Location and opening a 
PrEVilOGS LOGacLON. « & «~~ ¢ « &» & «.& @-9ed9 


1x 


OWWMOWMWMOWO WO WO WO 


CHAPTER 


CHAPTER 11 


CO “J OV OV OV OV OV OV OD 


Mmmm SS — & 


WWW WWNRrP PrP Pe 


maim me Be WW WWW Ww Ww 


NWO PWD PP 


m W DN 


NO 


Hm W NHN F 


USING 
The 
The 
The 
The 
The 
The 

EXAMP 

ZAP E 


SOURC 


SLP I 
The 


ZAP GENERAL PURPOSE COMMANDS 
X Command 
K Command 
O Command 
Equal Sign (=) 
V Command 
R Command 
LES 
RROR MESSAGES 


Command 


E LANGUAGE INPUT PROGRAM (SLIP) 


NPUT AND OUTPUT FILES 
Input File 


Command Input 


The 
The 
HOW S 
USING 
spe 
Ent 

E 

E 


U 
Upd 
G 


SLP Listing File 
SLP Output File 
LP PROCESSES FILES 
SLP 
cifying SLP Edit “Commands 


ering SLP Edit Commands : ; 
ntering SLP Commands intemacrively 3 
ntering SLP Commands Using Indirect 
Command Files a 


Sing SLP Operators 
ating Source Files With SLP 
enerating a Numbered Listing 


Adding Lines to a File 


D 

R 

Cre 
CONTR 
SLP 
Con 
Set 
Aud 
Cha 
Tem 
Del 
SLP M 
SLP 
SLP 


eleting Lines from a File 
eplacing Lines ina File 
ating Source Files Using SLP 
OLLING SLP 

Switches ; 

trolling the Audit “Trail. 
ting the Position and pie ee Ene 
it Trail 
nging the value of the made “Prail 
porarily Suppressing the Audit Trail 
eting the Audit Trail ; 
ESSAGES ’ 

Information Message 

Error Messages 


CONVERT UTILITY (CVT) 


9-20 
9-20 
9221 
9-22 
9-22 
9=23 
9-23 
9-24 
9-31 


LOZ 
LZ 
LO=3 
10-4 
10-4 
10-5 
10-6 
10-6 
10-8 
10-9 


L010 
10=10 
10-11 
10-11 
10-12 
10-14 
10-16 
10-17 
L013 
10-18 
10-19 


10-20 
10-21 
10-22 
10-23 
10-24 
10-24 
10-24 


CHAPTER 12 


CHAPTER 


CHAPTER 


eae 
12 
ae 
LZ 
er 
i232 
daar 
2 
TZ 
oe 
L23 


13 


13. 
ios 
133 
3. 
13% 
li 


13: 
LS. 
eo ae 


‘oe 
a 
se 
pe 
5 
ile 
13 
13% 


14 


Vas 
14. 
14. 
14. 
14. 
14. 
14. 
14. 
14. 
14. 
14. 


W W WwW 


WwW WWD PF NOM SS SF BR WD 


mo SP PP Le LP f 


nm UU ee WN bP 
U1 mem WN PF 


NO 


WW 


SYN WM SS WN FP 


PERIPHERAL INTERCHANGE PROGRAM (PIP) 
INVOKING PIP 
FORMAT OF PIP COMMANDS 
PIP DEFAULTS FOR FILE SPECIFICATION FIELDS 
PIP SWITCHES AND SUBSWITCHES 
Switches 
Subswitches 
SPECIFYING WILDCARDS 
Wildcards in Output File Specifications 
Wildcards in Input Specifications 
PIP ERROR MESSAGES 
PIP ERROR CODES 


OBJECT MODULE PATCH UTILITY (PAT) 


INVOKING PAT . 
PAT COMMAND LINE FORMAT 
HOW PAT APPLIES UPDATES 
The Input File 
The Correction File 


How PAT and the Task Bid der Update Obqeee 


Modules 4 ‘ 
Overlaying ines ie a Modute 
Adding a Subroutine to a Module 


Determining and Validating the Contents of 


a File 
PAT MESSAGES 
Information Messages 
Command Line Errors ‘ 
File Specification Errors 
Input/Output Errors 
Errors in File Contents or Format. 
Internal Software Error 
Storage Allocation Error 


FILE STRUCTURE VERIFICATION UTILITY (VFY) 


INVOKING VFY 

VFY COMMAND FORMAT 

VFY MODE OF OPERATION 

VFY VALIDITY CHECK 

VFY SWITCHES . a 
Directory Wali daton Switch (/DV) 
Free Switch (/FR) 
List Switen. (71) 
Lost Switch (/LO) 
Read Check Switch 

FILE ERROR REPORTING 


(/RC) 


X1 


12-1 
12-2 
12-3 
12-5 
12-8 
12-9 


12-10 


12-10 
12-11 
12-13 
12-23 


13-2 
13-2 
13-3 
13-4 
13-4 


13-5 
13-5 
ie oa 


13-8 
L339 


13-10 


13-10 
13614 
13-13 
13-15 
13-16 
Loi 


14-1 
14-2 
14-3 
14-3 
14-4 
14-4 
14-5 
14-6 
14-6 
14-6 
14-7 


14. 
14. 
14. 
14. 
14. 


I AV OV OV OD 


APPENDIX A 


APPENDIX B 


ao ME ape 


APPENDIX C 


FIGURES 


OW NF Fr 


Files Marked for Delete .. oe -« » 14-9 
Deleting a File Marked oe pales 14-10 


Deletion of Multiple-Allocated Blocks . 14-10 
RECOVering: Lost BlOCKS 2. w a & w @ 2 w @: deeto 
VEY ERROR MESSAGES « « «= «+ = ¢@© ¢ #& @ = «# 4 14-11 


FUNCTIONS INITIATED BY DCL COMMANDS 


ERROR MESSAGES 


GENERAL ERROR MESSAGES . .. 2. « « «© « « « « Bel 
L7O GRROR MESSAGES ¢ & #2: BR & &@ © -h ££ =~ @ a » Belg 


SAMPLE EDT INITIALIZATION FILE 


General Format for Object and Macro Library 
Files ; 7-4 
Universal Popa File Format oe ke a Le 
Contents of Library Header. . a: et we ot | PG 
Format of Entry Point Table Element Vey 
Format of Module Name Table Element 7-7 
Module Header Format for Object and Macro 


Libraries .. 7-8 

Module Header Format fon cnagenesd aoe le) 
Sample Files Used in LBR Examples 1-4 .. . 7-35 

Output Library File After Execution of 

Example 1 .. ee ws Geo 

Output Library File Pete Be oear ion ey: 

Example 2... i. i es PSO 

Output Library Vie Rees Execution “of 

EXample 3 « » = « . 7-36 
Sample Files for Universal Library Replace 
Example .. . 7-38 

Output bibeary File Bebes 7 oRsnye Replace: . 1-38 

MACRO Listing Before and After Running LBR 

with /S2Z oe Sl ee Gk ee ww me ee PE 

Memory Display for P/OS” at A EL Se 
OULDUL Of EMG CVE Utility se. & de de -S. oe oe, Sede 

Using. PAG gc we G2 Boe oe a & we oe Be eee 


TABLES 


mm RFF WO WO WO HO ~AI AI OT W WD W W W WW 
| 
mb BPWNHORNPRPR DW SB WN FP 


OO 4 


Argument Values for /SHOW Qualifier 
The Enable and Disable Qualifiers 
The /SHOW and /NOSHOW Qualifiers 
Status Bits ‘ 
Display for SHOW TASKS /ACTIVE 

Task Status Flags ; 

Summary of CMP Default Switch Settings 
LBR File Specifiers Defaults 2 
LBR Switches 

ZAP Arithmetic Operators : : 
ZAP Command Line Element Seoaratore 
ZAP Open and Close Commands 

ZAP General Purpose Commands 

SLP Operators 

SLP Switches : 

PuUnGTUACION. tO Specity Radix 

PIP Default File Specifications 

PIP Switches and Subswitches 

PIP Error Codes and Messages 

VFY Switches and Functions : : 
Functions Initiated by DCL Commands 
I/O Brror Messages 


ann Be 


PREFACE 


Manual Objectives 


After reading this manual, you will be able to use the command 
language and utilities included in the PRO/Tool Kit. 


This book does not describe how to use the Professional computer, 
nor does it describe how to write applications. For information 
on using the Professional, including installing your application, 
see the Professional 300 Series User’s Guide for Hard Disk 
System. For information on writing applications, see the Tool 
Kit User’s Guide. 


Intended Audience 


Readers who already know a command language will benefit most 
from this manual. You should have a working knowledge of the 


application development cycle as described in the Tool Kit User’s 
Guide. 


Structure of This Document 
This manual consists of the following chapters: 


e Chapter 1 provides an introduction to the PRO/Tool Kit 
Digital Command Language (DCL) and an explanation of DCL 
command line format. 


® Chapter 2 describes the structure of the DCL command line, 
operation of the DCL Single Line Editor (SLE), how to use 
P/OS file specifications, and the foreground and _ background 
processing feature of P/OS. | 


e Chapter 3 lists alphabetically the PRO/Tool Kit DCL commands, 
and includes a description and syntax for invocation of each 


command. 


e Chapter 4 details the Indirect Command Processor, which 
processes command files. 


e Chapter 5 describes the File Compare (CMP) utility, which 
compares the contents of two ASCII files. 


XV 


Chapter 6 explains the File Dump (DMP) utility, which allows 
you to examine the contents of a file or volume of files. 


Chapter 7 describes the Librarian (LBR) utility, which allows 
you to create, update, modify, list, and maintain library 
Files. 


Chapter 8 describes the Resource Monitoring Display (RMD), 
which allows you to display information about the resources 
in your system. 


Chapter 9 describes the Task/File Patch Program (ZAP), which 
allows you to directly examine and modify task image and data 
files. 


Chapter 10 describes the Source Language Input Program (SLP), 
a utility that you can use to maintain and audit source 
files. 


Chapter 11 shows you how to convert numbers among different 
radixes uSing the Convert Utility (CVT). 


Chapter 12 tells you how to perform file control operations 
using the Peripheral Interchange Program (PIP). 


Chapter 13 describes how to update, or patch, code in a 
relocatable binary object module using the Object Module 
Patch Utility. (PAT). 


Chapter 14 tells you how to use _ the File Structure 
Verification Utility (VFY), which allows you to check the 
readability and validity in files, directories, and volumes. 


Appendix A contains functions initiated by DCL commands. 


Appendix B lists the common error messages for PRO/Tool Kit 
DCL and the utilities. 


Appendix C contains an EDT command file example. 


Associated Documents 


PRO/Tool Kit Installation Guide and Release Notes 
For directions on installing the PRO/Tool Kit, as well as 


inforhation. specific to the current. version. of the PRO/Tool 
Kit, read this document. 


ares 


Professional 300 Series User’s Guide for Hard Disk System 


You should read this manual if you are not familiar with the 


Professional. 


Tool Kit User’s Guide 


This manual 


provides 


details the program development cycle, and 


primary information on devices, volumes, and file 


Specifications. 


Conventions Used in This Document 


Convention/Term 


[optional ] 


UPPERCASE 


lowercase 


[Ss] 


or 


[,S] 


Meaning 


In a command line, Square brackets indicate that 
the enclosed item is optional. In a_e file 
Specification, however, square brackets are part 
of the required syntax. 


Uppercase words and letters, used in examples, 
indicate that you should type the word or letter 
exactly as shown. 


Lowercase words and letters, used in format 


examples, indicate that you should substitute a 
word or value of your own. Usually the lowercase 
word identifies the type of substitution 
required. 


If you can repeat an item in a command line, 
then an [Ss] appears after the item to show its 
plural form. A comma or other’ punctuation 
preceding the letter "s" indicates that you must 
separate repeated items with that punctuation. 


A vertical ellipsis in a figure or example means 
that not all of the statements are shown. 


eV 11 


Convention/Term 


<CR> 


<CTRL/x> 


BOLD 


Tool Kit 


Host Tool Kit 


PRO/Tool Kit 


Meaning 


This manual occasionally shows carriage returns, 
represented by <CR>, to delineate an example 
elearty.: 


This notation indicates that you are to. press 
the key marked ‘Ctrl" while Simultaneously 
pressing another key on the keyboard. 


Interactive user input appears in red. 


In command syntax, the bold portion indicates 
the minimally-acceptable abbreviation for the 
command. 


This general term refers to the software you use 
to develop applications to run on a Professional 
COMpPUCET « 


The Host Tool Kit is Tool Kit software that runs 
on a host computer, rather than on the 
Professional itself. 


The PRO/Tool Kit is the Tool Kit software that 
runs on the Professional computer. 
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CHAPTER 1 
INTRODUCTION 


The PRO/Tool Kit is an application that allows you to perform 
program development on the Professional. It includes PRO/Tool 
Kit DCL, a command language, as well as several utility programs 
that aid you in the development process. This chapter introduces 
PRO/Tool Kit DCL and the PRO/Tool Kit utilities. 


For information on hardware and software requirements ror 
Installing the PRO/Tool Rie; as well as installation 
instructions, see the PRO/Tool Kit Installation Guide and Release 
Notes. | 


1.1 PRO/TOOL KIT DCL 


The PRO/Tool Kit DCL is a subset of Digital Command Language 
implementations found on the VAX/VMS and RSX-11M-PLUS operating 
systems. Although some commands are unique to the PRO/Tool Kit, 
many of the commands derive from both of these operating systems. 


PRO/Tool Kit DCL provides you with an extensive set of commands 
to perform various functions. You can divide the PRO/Tool Kit 
DCL commands into five groups: 


File Manipulation 
Program Development 
Task Manipulation 
Set and Show 


Miscellaneous 
The following sections describe the commands within each 
functional group. Chapter 5 presents the commands in 


alphabetical order. 
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1.1.1. File/Device/Volume Manipulation Commands 


The file manipulation commands are: 


APPEND DISMOUNT 
ASSIGN DUMP 

BAD EDIT 
CONVERT EDIT/PROSE 
COPY EDIT/SLP 
CREATE FORMAT 
DIRECTORY INITIALIZE 
DEASSIGN MOUNT 
DEFINE PRINT 
DELETE PURGE 
DELETE/DIRECTORY RENAME 
DIFFERENCES TYPE 
DIRECTORY UNLOCK 


1.1.2 Program Development Commands 


The program development commands are: 


BASIC LIBRARY /INSERT 
COBOL LIBRARY/LIST 
DEBUG LIBRARY /REMOVE 
DIBOL LIBRARY /REPLACE 
FORTRAN LINK 

LIBRARY LINK/C81 
LIBRARY/COMPRESS LOAD 
LIBRARY/CREATE MACRO 
LIBRARY/DELETE PASCAL 

LIBRARY /EXTRACT UNLOAD 


1.1.3. Task Manipulation Commands 


The task-related commands are: 


ABORT REMOVE 

ASSIGN/TASK RUN uninstalled task 

CANCEL RUN installed task 

CONTINUE SPAWN 

FIX START 

INSTALL START /UNBLOCK 
STOP/BLOCK 
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1.1.4 Set and Show Commands 


The set and show commands are: 


SET [DAY]TIME SHOW DEFAULT 

SET DEFAULT SHOW DEVICES 

SET DEVICE SHOW LOGICALS 

SET HOST SHOW MEMORY 

SET PRIORITY SHOW TASKS 

SET PROTECTION SHOW TASKS/ACTIVE 

SET TERMINAL SHOW TASKS/INSTALLED 

SHOW ASSIGNMENTS SHOW TASKS/DYNAMIC 

SHOW CLOCK_QUEUE SHOW TASK: taskname/DYNAMIC 

SHOW COMMON SHOW TASKS/ACTIVE/DYNAMIC 

SHOW [DAY]TIME SHOW TASK/LOGICAL_UNITS 
SHOW TERMINAL 


1.1.5 Miscellaneous Commands 
The miscellaneous commands are: 


CLEAR 
EAIT 
HELP 
MAIL 
PHONE 


1.2 PRO/TOOL KIT UTILITIES 


The PRO/Tool Kit utilities comprise the following: 
e The Compare Utility (CMP) 
and SLP editors 


e The EDT, PROSE, 


® Frame Development Tool (FDT) 
@ The PRO/FMS-11 Forms Editor (PROFED) 

@® The PRO/FMS-11 Forms Utility (PROFUT) 
® The Librarian Utility (LBR) 


e The Resource Monitoring Display (RMD) 
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® Various RMS utilities 

@ The Task/File Patch Program (ZAP) 

® The Convert Utility (CVT) 

@® The Peripheral Interchange Processor (PIP) 

@ The Object Module Patch Utility (PAT) 

e The Verify Utility (VFY) 
You can invoke most of these utilities through a corresponding 
DCL command. Those utilities that you cannot call through DCL 


must be invoked directly. Refer to the specific utility below 
for instructions. 


1.2.1. Program Development, Frame, and Form Utilities 
These utilities allow users to perform the following functions: 
® Edit text files using a text editor (such as EDT) 

e Develop menus with the Frame Development Tool (FDT) 


e Assemble MACRO-11 source files with the Professional MACRO-11 
Assembler (PMA) 


e Build applications with the Professional Application Builder 
(PAB) 


@® Invoke the Record Management Services 


You should refer to. the corresponding Tool Kit. Documentation ‘for 
a complete description and operating instructions for these 
UtitLeres. 


e Text Editors To invoke EDT, the DIGITAL standard text editor, 
use the commands EDIT, EDIT/EDT, or the following command: 


penta am ee a oe cont yong, gem, peongiy 
LeTTN jy 
a ho LY tpt cond Sand sch 


If you prefer, you can use the PROSE editor instead of EDT. 
To invoke PROSE, use the command EDIT/PROSE. In addition, 
the SLP editor is available; to invoke SLP, use the command 
EDIT/SLP or the command RUN SSLP. 
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FDT (Frame Development Tool) 


FDT creates interactive menus for P/OS applications. The 
following command invokes this utility: 


S RUN SFDT 


For complete details on FDT, see the Tool Kit Reference 
Manual. 


PROFED (PRO/FMS-11 Forms Editor) 


PROFED 1s an editor that lets you create and modify video 
forms on the screen. The use of the PRO/FMS-11 Forms utility 
(PROFUT) translates these forms into files for use by an 
application program. The following command invokes this 
utility: 


See the FMS-11/RSX Software Reference Manual for details on 
using PROFED. 


PROFUT (PRO/FMS-11 Forms Utility) 


PROFUT creates form description files that are the output 
from the PRO/FMS-11 forms editor. An application program can 
display these files. The following command invokes’ this 
Wet aky: 


See the FMS-11/RSX Software Reference Manual for details on 
using PROFUT. 


PAB (Professional Application Builder) 


The Professional Application Builder links one or more object 
modules into an executable task image, which is the final 
form of any application or system program. PAB resolves 
addressing and overlay considerations. To invoke PAB in DCL, 
use the LINK command or the command RUN SPAB. 


PAB is based on the RSX-11M/M-PLUS Task Builder. Refer to 
the RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for 
additional information on PAB. 
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® PMA (Professional MACRO-11 Assembler) 


PMA assembles and lists MACRO-11 source files. The MACRO 
command, or the command RUN SPMA, invokes this utility. 
Refer to Chapter 3 and the PDP-11 MACRO-11 Language Reference 
Manual for further details on the MACRO-11 assembler). 


1.2.2 RMS Utilities 
The PRO/Tool Kit contains the utilities listed in this section. 
NOTE 
Refer to the RSX-11M/M-PLUS RMS-11 Utilities 
Manual for a description of the RMS utilities. 


Only those RMS utilities listed below are 
Supported on the PRO/Tool Kit. 


@ RMSCNV 
RMSCNV is the RMS-11 file conversion utility that moves 
records between two RMS-11 files of any organization or 
record format. You can invoke RMSCNV_ by typing the 
following: 


S RUN SRMSCNV 


You can also use the DCL command CONVERT. 


@ RMSDES 
RMSDES allows you to design and create indexed, sequential, 
and relative files. You can specify the file attributes 


interactively or read in the attributes of an existing, 
external data file that you want to re-create with little or 
no modification. You can invoke RMSDES by typing the 
following: 


S RUN SRMSDES 


There is no other DCL command to invoke RSMDES. 
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® RMSDSP 


RMSDSP lists RMS-11 file attributes and structural data. You 
invoke this utility by typing the following: 


S RUN SRMSDSP 
You can also use the DCL command DIRECTORY/ATTRIBUTES. 
@ RMSIFL 

RMSIFL indexed file load utility builds an indexed file using 
records from another RMS-11 file of any organization type. 
This utility uses techniques that are derived from the basic 
Structure of indexed files, rather than from the standard 
RMS-11 file structure. You invoke this utility by typing the 
following: 


S RUN SRMSIFL 


There is no other DCL command to invoke RMSIFL. 


1.2.3 Other Utilities 

Chapters 5 through 14 fully describe the CMP, DMP, LBR, RMD, ZAP, 
SLP, CVT, PIP, PAT, and VFY utilities, respectively. The syntax 
you use to invoke these is: 


S RUN Sutility-name 


The utility then displays its prompt. 


CHAPTER 2 
USING PRO/TOOL KIT DCL 


You can use PRO/Tool Kit DCL interactively by typing a command at 
the keyboard, or you can invoke a DCL command file using the 
Indirect Command Processor (refer to Chapter 4). Whichever 
method you use, the format of the command is the same. 


You enter your commands at the DCL command level (indicated by 
the S$ prompt), and press either the <RETURN> or <DO> key to 
execute the command. Because P/OS waits for a carriage return 
before processing the DCL command, you can edit the command line 
before pressing <RETURN>. (See Section 2.2.) 


You are only required to type as many letters of the DCL command 
as needed to form a unique command. For example, the 
abbreviation SET TE/UP is a valid, unique command, because there 
are no duplications of this within the SET TERMINAL command or 
within the PRO/Tool Kit Command Language (refer to SET TERMINAL 


in Chapter 3). However, SET TE/IN would not be a unique command, 
because this abbreviation Gourd stand ror either SEE 
TERMINAL/INQUIRE or SET TERMINAL/INTERACTIVE. (Refer to Section 


2.1.4 for additional information on abbreviating DCL commands.) 


2.1 THE DCL COMMAND LINE 


This section introduces the rules governing the use of DCL. The 
examples in this section are intended to illustrate these rules, 
not to document the full capabilities of the commands. For more 


detail, see the individual command descriptions in Chapter 3. 


A command consists of a command name, or verb, describing the 
action the system is to take. Most commands also include one or 
more parameters and qualifiers to further define the action of 


the command. Qualifiers are preceded by a slash (/) and 
parameters are preceded by a_e space. Both qualifiers and 
parameters can take arguments. Arguments are preceded by a colon 


(:). The format of a PRO/Tool Kit DCL command is: 


2-1 
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9 Command/cmd-qual[s] parami[/param-qual] param2[/param-qual ] 


where: 

S indicates the DCL command level prompt. 

Command is the name of the DCL command. 

/cmd-qual 1s an optional command gualifier that directs 
the command either to perform or omit auxiliary 
functions. 

paraml iS a parameter that you pass to the command for 
processing (not required by all commands). 

param-qual iS an optional parameter qualifier that causes 
the DCL command to perform or omit auxiliary 
Functions on the parameter. 

param2 is a second parameter that you pass to the DCL 
command for processing (not required by all 
commands). 


Either the <RETURN> or <DO> key is the terminator that passes DCL 
commands to the operating system. Unless the action of the 
<RETURN> key differs greatly from what is expected, the command 
examples and formats in this manual do not include an indication 
that each command line is terminated by a carriage return. (See 
Section 2.1.6 for a discussion of command lines that are too long 
to fit on one line of your terminal.) 


Some commands require parameters or arguments as part of the 
command line. If you fail to supply a required command element, 
DCL prompts you with one or two words indicating the general 
nature of the required element. If you do not understand the 
prompt, type a question mark (?) for help. (In some cases, an 
omission causes an error rather than a prompt.) 


2.1.1 Prompting 


The prompts help you learn the form of a command by requesting 
that you supply required command elements. 


For example, the RENAME command works as follows: 
S RENAME 


PPOM:: PLB tsi 
To? FILE2.MAC 
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The one-line format for RENAME is: 
S RENAME FILE1L.LIS FILE2.MAC 


The formats can be mixed. DCL prompts for whatever you leave 
out. For example: 


S RENAME FILE1.LIS 
To? FILE2.MAC 


There are no defaults for prompts. You must supply a response to 
any prompt. If you do not want to continue with the command, 
type a CTRL/Z. 


2.1.2 Qualifiers 


Qualifiers modify the action of the command. Qualifiers always 
Start with a slash (/) and are generally optional. 


Qualifiers are either command qualifiers or parameter qualifiers. 
Most qualifiers are command qualifiers. In this manual, command 
qualifiers are always shown immediately following the command 
verb, as in this example: 

S TYPE/TODAY *.HLP 
However, most command qualifiers can appear anywhere in_ the 
command line. Another name for these qualifiers is floating 
qualifiers. The following examples illustrate how command 
qualifiers can float: 

S TYPE *.HLP/TODAY 


or 


S TYPE 
File(s)? *.HLP/TODAY 


or 
S TYPE 
File(s) 2° “TODAY 
File(s)? *.HLP 


You can mix formats, as in the following example: 


S TYPE/TODAY 
File(s)? *.HLP/EXCLUDE:HELPF.HLP;* 
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or 


S TYPE/TODAY 
File(s)? *.HLP/ 
Qualifier? EXCLUDE:HELPF.HLP;* 


or 


S TYPE/TODAY 

File(s)? / 

Qualifier? EXCLUDE:HELPF.HLP;* 
File(s)? *.HLP 


Note that you are prompted for a qualifier when a slash with no 
qualifier attached appears on the command line. When you supply 
the qualifier, do not type the slash again. 


Regardless of where the qualifier appears, it has the same 
effect. 
Qualifiers described as parameter qualifiers, or filespec 


qualifiers, cannot float. 

Parameter qualifiers do not modify the action of the command; 
they modify the action of the command as it concerns that 
particular parameter, or supply additional information needed for 
the command to execute properly. For instance, in the following 
example: 


S MACRO HIYA, TESTBLD/LIBRARY, PIGEON 


the qualifier /LIBRARY identifies a particular file as being a 
library, and the /LIBRARY qualifier cannot float. 


Many qualifiers can be negated by prefixing NO or - (minus) to 
the qualifier name. Thus, the command: 


S MACRO/OBJECT SIMPLE.MAC 


directs the MACRO-11 Assembler to make an object file, while the 
command: 


S MACRO/NOOBJECT SIMPLE.MAC 


S MACRO/-OBJECT SIMPLE.MAC 
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directs the MACRO-11 Assembler to omit the object file. In the 
first example, /OBJECT is the default qualifier and need not be 
explicitly included. In other words, unless your MACRO command 


includes the /NOOBJECT qualifier, an object file is produced. 


2.1.3 HELP 


HELP is available for all DCL commands by entering the HELP 
command or by typing a question mark (?) in response to any DCL 
prompt. For instance, if you want help on the TYPE command, 
enter the following: 


S HELP TYPE 
The following HELP text is displayed: 


TYPE[/qualifier[{s]] filespec[s] 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 
/EXCLUDE: filespec 


The TYPE command displays the contents of text files on your 
terminal. 


If you wish help on one of the qualifiers for TYPE, enter’ the 
following: 


S HELP TYPE TODAY 
TYPE/TODAY filespec[s] 


The /TODAY qualifier specifies that you wish the TYPE 
command to type only files created today. 


The HELP text consists of a brief explanation of the command 
followed by an illustration of the syntax, showing that TYPE 
accepts one or more filespecs, and one or more qualifiers. 


If you wish help while being prompted by the TYPE command, use 
the following procedure: 


S TYPE 

PLlets 2 < | 

TYPE | /qualifier{s |] fitespec(s | 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
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/ THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 

/EXCLUDE: filespec 


The TYPE command displays the contents of text files on your 
terminal. 


File(s)? 


The same help text is printed on your terminal, but the prompt 
returns, meaning the TYPE command is still waiting for you to 
list the file(s) you wish typed. 


You can also get help on a specific subtopic while being prompted 
by a command, by responding to the prompt with a question mark. 
For example: 


S SET 
Function? ? 
SET thing 


The SET command can be used to set something. The 
following things can be set with this command: 


[ DAY | TIME DEFAULT DEVICE PRIORITY PROTECTION 
TERMINAL 


To get help on a specific subtopic of the SET command, enter a 
question mark followed by the subtopic: 


Function? ? DEFAULT 
SET DEFAULT [ddnn:][directory] 


The SET DEFAULT command sets your default directory or 
device, or both. 


Function? 


You can also get help by typing a question mark in response _ to 
the DCL prompt ($). 


If you should decide after reading the help text that you have 
chosen the wrong command, enter a <CTRL/Z> in response to the 
prompt to end the execution of the command. (A <CTRE/Z>- en 
response to a prompt always cancels execution of the current DCL 
command. ) 
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2.1.4 Abbreviations 


It 1s rarely necessary for you to type either the complete 
command name or the complete qualifier name. You only need to 
type the characters required to distinguish the command or 
qualifier from all others. 


For example: 


@® TYPE can be abbreviated as T because it is the only command 
beginning with that character. 


@® DELETE can be abbreviated as DEL, but not DE. 

®© DEASSIGN can be abbreviated as DEA, but not DE. 
Three letters is usually enough. Five letters is always enough. 
You can often omit other parts of commands as well. 
The underscore character (_) is used to make DCL commands’ more 
readable where two words are needed to name a single command 
element, such as EDIT/READ_ONLY. However, you need not type the 
underscore to enter the command. EDIT/READ_ ONLY is the same as 


EDIT/READONLY. 


Here are the brief forms for some frequently used commands. 


A for ABORT C for COPY DD. tor DERECTORY 
DEA for DEASSIGN E for EDIT F for FORTRAN 

H for HELP iy £Or INK M for MACRO 

R for RUN S for SHOW T for “TYPE 


The command descriptions in Chapter 3 indicate the minimum 
acceptable abbreviation for each command. 


2.1.5 Colon and Equal Sign 


The command descriptions in this manual show arguments set off by 
a colon (:). You can always replace such colons with an equal 
Sign (=), as in this example: 


S DIFFERENCES/LINES=2 testfile.tmp 
Refer to Section 3.20 for a description of the DIFFERENCES 


command. Colons in device names, such as DW1:, and so forth, 
cannot be replaced by equal signs. 
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2.1.6 Command Line Continuation 


The hyphen (-) is used to indicate line continuation. When you 
end a command line with a hyphen and a carriage return, the DCL 
continuation prompt ($-) indicates that you can continue entering 
the command line. Tf you are continuing a line from a prompt, 
Such as: 

Task? 


that prompt is the indication that the line is being continued. 
This feature permits you to enter command lines including more 
characters than your terminal has room for on one line. No DCL 
command line can be longer than 250 characters. Here is an 
example of line continuation: 


5S COPY PROCOM1.PAS,PROCOM2.PAS,PROCOM3.PAS,-<CR> 
S- BIGFILE.PAS [WORK] 


The command is not entered until DCL encounters a line ending 
with a carriage return not preceded by a hyphen. In the example, 
the first carriage return does not enter the command because it 
is preceded by a hyphen. The command is entered following the 
second carriage return. The carriage return can be on a line by 
itself. 


2.1.7 Comments in Command Lines 


You can include comments in a DCL command line using the 
exclamation porn. 01). 


If the comment ends the command line, only a single exclamation 
point is needed, as in this example: 


S COPY PROCOM1.PAS PROCOM1.TMP ! Temporary file 


If the comment is within the command line, two exclamation points 
are needed, as in this example: 


> COPY t¥enporary File! PROCOM?: PAS PROCOML.7MP 
These comments are ignored and not interpreted in any way by DCL. 
Comments can be placed at any natural break in the command line: 


between qualifiers, between parameters, even as part of a 
response to a prompt. 
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2.1.8 Errors 


You can correct typing errors or delete the line completely by 
using the <DELETE> key, or <CTRL/U> (provided you have not 
terminated the line). 


You can cancel the execution of any DCL command by typing a 
<CTRL/Z >< 


If the system detects an error in the command line input, it 
returns the appropriate error message. 


Here are some examples of incorrect commands and the error 
messages they produce: 


S KOPY PRO300.LIS PRINT.LIS 
DCL -- Illegal command 


S RENAME/COPY TEST.PAS PROCOM1.PAS 
RENAME -- Illegal or contradictory qualifier 
RENAME/COPY TEST.PAS PROCOM1.PAS 


S DIFFERENCES/LINES=TWO TEST.PAS PROCOM1.PAS 
DIFFERENCES -- Numeral expected 
DIFFERENCES/LINES=TWO TEST.PAS PROCOM1.PAS 


In the first case, the error was detected by DCL, as indicated by 
the first part of the error message. There is no DCL KOPY 
command. The entire command was rejected. 


In the second case, the command was entered correctly, but the 
qualifier was incorrect. The first part of the message shows 
that the error was detected within the RENAME command itself. 
The command is reprinted and a circumflex (~) points to the 
error. 


In the third case, the command and qualifier were correct, but 
the argument was in error. The message explains the error and 
the circumflex points to the error. 


Sometimes the circumflex does not point directly at the error, 
but at the point at which the command started to go wrong, which 
may be several characters before the actual error. 


Typing mistakes are by far the most common cause of errors. 
Retyping the command or using the <UP ARROW> and the Single Line 
Editor (SLE) often eliminates the error. (See the discussion of 
the Single Line Editor, below.) Other common causes of errors are 
omitting a space or other delimiter in a command line, specifying 
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invalid devices or nonexistent files, and failing to type a 
sufficient number of characters to distinguish the command or 
command element. 


All the DCL error messages are listed and explained in Appendix B 


of this manual. In some cases, such as assembly errors, you may 
need to go to another manual for explanation of the error. 


2.1.9 PRO/Tool Kit DCL Initialization and Termination Files 


When you enter the PRO/Tool Kit, two indirect command files 
automatically execute. Similarly, two indirect command files 
automatically execute when you leave the PRO/Tool Kit. These 


initialization and termination files install and remove tasks 
that you need for developing applications on the Professional. 


The initalization files execute in the following order when you 
enter the PRO/Tool Kit: 


1. LB:[{ZZPRODCL]START.CMD 


This is the first command file to execute. It executes 
automatically for all users of the PRO/Tool Kit. Commands 
that should always be executed during PRO/Tool Kic 
initialization are located in this file. Only a system 
manager should modify this file. For examcle, if all 
PRO/Tool Kit users on a system require a particular library, 
the system manager could modify LB:[ZZPRODCL]START.CMD to 
install that library. 


2. DCLAPPLSDIR:START.CMD 


This command file is located in a user-specific area, 
DCLAPPLSDIR, and s0 it can be different for each user. For 
instance, if you are the only user who needs ae certain 
library installed, you can modify DCLAPPLSDIR:START.CMD to 
perform the installation during your PRO/Tool Kit session. 
Alternatively, you might place the comment character before 
lines that install tasks you do not use. 


The termination command files execute in the following order when 
you leave the PRO/Tool Kit: 
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LB: [ZZPRODCLJEXIT.CMD 


This command file is provided so that you can _ specify 
commands to be executed ona system-wide basis during DCL 
termination. The termination file corresponds to the 
initialization file LB:[{ZZPRODCL]START.CMD. 


DCLAPPLSDIR:EXIT.CMD 


This command file is provided so that you can. specify 
commands to be executed on a user-specific basis during DCL 
termination. The termination file corresponds tO the 
initialization file DCLAPPLSDIR:START.CMD. 


See Chapter 4 for information on indirect command files. 


2.2 CORRECTING MISTAKES WITH THE DCL SINGLE LINE EDITOR 


This 1s a brief description of how the Single Line Editor works. 


The Single Line Editor can be used in two ways: 


If you make a mistake before you press either <RETURN> or 
<DO>, you can correct it without retyping the entire command. 
To correct the command, press the <LEFT ARROW> key until the 
cursor is just to the right of any character(s) you want to 
change. Delete the part you do not want with the <X] key and 
retype. To adda part you left out, move the cursor to the 
place and type in the omitted part. The rest of the command 
will move to the right to make room. 


If you make a mistake after you have pressed either <RETURN> 
or <DO>, press the <UP ARROW> key. The command will be 
redisplayed for changing. You can display up to nine 
previous commands this way. You can then use the <DOWN 
ARROW> key to display the next command. 


While entering DCL commands, the <CANCEL> key erases’ the 
current command so you can start over. The <F13> function 
key erases from where the cursor is to the end of the line. 


Normal text characters simply get entered into the command line 


at 


the position of the cursor. If there are any characters on, 


or to the right of the cursor, they will move to the right to 
make room for the new character. 
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The following list describes what keys on the keyboard perform 
what functions in the single line editor. 


<X] 


<REMOVE> 


<RETURN> 
<DQ> 


<LEFT ARROW> & 
<RIGHT ARROW> =» 


<UP ARROW> t 


<DOWN ARROW> Jf 


<F13> 


<EXIT>D 


<HELP> 


<CANCEL> 
<CTRL/U> 
£CTRE/CS 


<CTRL/R> 
<CTRL/W> 


Erases the character to the left of the cursor. 
If there are any characters on, or to the right 
of the cursor, they will move to the left to 
close the space for the erased character. 


Erases the character on the cursor. If there 
are any characters to the right of the cursor, 
they will move to the left to close the space 
for the erased character. 


Enters the current command, giving it to the 
DCL command interpreter for execution. After 
the command has executed, the line following 
the one that was just entered (if there is one) 
will be displayed, with the cursor at the end 
of the line. To execute it, press <RETURN>D or 
<DO>. To skip over it, press the down arrow. 


Moves the cursor one column to the left or to 
Che. .rignet. 


Stores the current command, and displays the 
previous command, leaving the cursor at the 
end. If there is no previous command, no action 
is taken. 


Stores the current command, and displays the 
next command. If there are no more commands, 
then just start an empty line. 


Erases the command from the cursor position to 
the end of the line. 


Leaves the PRO/Tool Kit and returns to the P/OS 
Main Menu. 


Appends "HELP" to the beginning of the current 
command, and enters it. 


Erases the entire current command, and starts 
with a blank command. 


Redisplays the current command. 


P/OS FILE SPECIPICATIONS- IN. DCL 


2.3 P/OS FILE SPECIFICATIONS IN DCL 


File specifications, often called filespecs, are required for 
many DCL commands. The format of a file specification is as 
follows: 


nodespec: :device:[directory]filename.type;version 


Note that the nodespec portion of a file specification is valid 
only on those commands supported by PRO/DECnet, as indicated in 
the command descriptions in Chapter 3. Your Professional must 
have PRO/DECnet installed in order to use the nodespec to operate 
on files at other nodes on the network. 


See the Tool Kit User’s Guide for a complete description of file 
specifications. 


2.3.1 Wildcard Features in DCL 


PRO/Tool Kit DCL offers wildcard features that are in addition to 
the simple wildcard capability available throughout P/OS (see the 
Tool Kit User’s Guide). In the simple form of wildcarding, you 
use the * to replace an entire field ina filespec. 


Many commands described in this manual work through PIP, the 
Peripheral Interchange Program. For the PIP-related 
commands--DIRECTORY, DELETE, PURGE, COPY, RENAME, TYPE, APPEND, 
UNLOCK, and SET PROTECTION--a more elaborate form of wildcarding 
is available. In these commands, within filenames and file 
types, the * can be used in a more complex manner. The * 
actually means "match zero or all characters in this position." 


Therefore, the command: 

S DIRECTORY G4. TAT 
lists the most recent versions of all files with the type .TXT 
whose names start with L on the default volume and in the default 
directory. 
And the command: 

S DLRECTORY *L4%.-TXT 
lists the most recent versions of all files with the type .TXT 


whose names include an L on the default volume and in the default 
directory. 
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The same substitutions can also be used in file types, so that 
the command: 


S: DIRECTORY SNOBLO.E* 
lists the most recent versions of all files with the name SNOBLO 
and the type beginning with an L on the default volume and in the 
default directory. 
You can use more than one wildcard in filenames and file types. 
The command: 


S DIRECTORY *#F*D*<Tx?T 


lists the most recent versions of all files with the type .TXT 
whose names include an F and aD in that order. 


In addition, the PIP-related commands permit the percent sign (3%) 
to be used as a wildcard, but only within filenames and file 


types. The % means "match exactly one character in this 
position." 


For instance, the following command: 
S DIRECTORY %.TXT 


lists all files with the type .TXT and a= single-character 
filename on the default volume in the default directory. 


The command: 
S DIRECTORY NOV%$%81.TXT 


lists all files with the type .TXT and a filename consisting of 
NOV and 81 separated by two characters on the default volume in 
the default directory. 


The wildcards can be combined ina single filespec. 
The command 
S$ DIRECTORY %L*T.TM% 
lists all files whose names begin with a single character 
followed by an L and end with a T, and with a file type 


consisting of .TM and another single character on the default 
volume in the default directory. 


P/OS FILE SPECIFICATIONS IN DCL 


Wildcarding, combined with systematic usage of directory 
structure, filenames, and file types, can add considerable 
flexibility and convenience to your use of the system. 


2.3.2 Logical Name Translation 


You can specify a logical name to stand for either a part or 
whole file specification. For example, you can define the 
logical name INPUT to have an equivalence consisting of the file 
Specification BIGVOLUME:[USERFILES]NAMES.TXT. Subsequently, you 
can use INPUT wherever you would normally use the file 
specification. See the Tool Kit User’s Guide for more 
information on logical names. 


Note that PRO/Tool Kit commands translate logical names only when 
a device, directory, or file specification is expected. 


2.4 FOREGROUND AND BACKGROUND PROCESSING 


Once you initiate a command, you cannot type another command 
until the first command has completed execution. In this case, 
you initiated the command in foreground mode. Typing <CTRL/C> or 
<INTERRUPT/DO> halts the execution of a command or program in 
foreground mode. 


You can initiate commands or programs in background mode through 
the use of the SPAWN command. Once you have initiated such a 
command or program, you can issue other commands or run programs 
at your terminal; you need not wait for the background command or 
program to complete execution. In order to halt the execution of 
a command or program running in background mode, you must use the 
ABORT commmand. 


2.4.1 <CTRL/C> 


<CTRL/C> or the <INTERRUPT/DO> key sequence aborts the command 
you just typed at the terminal. <CTRL/C> cancels command entry 
or processing, and interrupts command or program execution, 
returning control to DCL. However, <CTRL/C> will not abort a 
commmand or program that you initiated with the SPAWN command. 
You must use ABORT to halt the execution of such a command or 
program. 
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FOREGROUND AND BACKGROUND PROCESSING 


For example, if you just typed DIRECTORY and realized you did not 
want to execute the DIRECTORY command, use of <CTRL/C> will abort 
the action of the DIRECTORY command. 


2.4.2 ABORT 


This command halts execution of commands and programs running in 
background mode. 


NOTE 


You must abort the task name, not the name of the 
command that invoked its execution. If you use 
SPAWN to initiate a DCL command in background 
mode, that DCL command runs as a task with a task 
name of the form xxxTn, where xxx are the first 
three characters of the DCL command, and Tn is 
the name of the terminal from which the command 
was issued. 


To determine the name of the task running in background mode, use 
the SHOW TASKS command. 


NOTE 


You should never initiate a command or _ program 
that attaches the monitor in background mode, 
because you cannot abort it. 


CHAPTER 3 
DCL COMMANDS 


This chapter lists the PRO/Tool Kit DCL commands alphabetically 
and provides description, syntax, options, and command prompts 
for each command. Note that in the syntax description of each 
command, the portion of the command shown in bold indicates the 
minimally acceptable abbreviation. 


Some of the PRO/Tool Kit DCL commands can be used for network 
operations, or have qualifiers that enable network operations. 
In order to use these commands and qualifiers for network 
operations, you must first install the PRO/DECnet Tool Kit. When 
you install the PRO/DECnet Tool Kit, the DCL extensions are also 
automatically installed. See the PRO/DECnet Installation Guide 
for details. 


ABORT 


3.1 ABORT 


ABORT forces an orderly end to a running task or to the action of 


a specfic command. Nonprivileged users can abort any task 
running on TI:. Privileged users can abort any task. 
Syntax 


ABORT [/COMMAND] [/qualifier] commandname 

ABORT/TASK [/qualifier] taskname 
qualifier 

/ COMMAND 


/ TASK 
/TERMINAL: ttnnn: 


commandname 
Specifies the command whose effect you want to cancel. This 
parameter can be used only when the /TASK qualifier is not 
present. You must specify at least the first three 


characters of the command verb. 


taskname 
Specifies the name of the task you want to abort. This 
parameter requires the presence of the /TASK qualifier. If 


you use the /TASK qualifier and do not specify a task name, 
you will get the error message "Illegal task name." 

Prompts 
Taskname? taskname 

Command Qualifiers 

/COMMAND 


Specifies that you want to abort a command. This is the 
default qualifier and need not be specified. 


ABORT 


/TASK 


Specifies that you want to abort a task by name. 


/TERMINAL: ttnnn: 


Specifies that a task from some terminal other than your own 
be aborted. This is a privileged qualifier. 


Example 


S SPAWN LINK filespec 
S ABORT LINK 


In this example, the user issued a LINK command in the background 
by using the SPAWN command. Rather than waiting for the command 
to complete, the user entered the ABORT command to terminate the 
command. 


SSPAWN LINK filespec SABORT /TASK LINTIL 


In this example, the user issued a LINK command in the background 
by using the SPAWN command. Rather than waiting for the command 
to complete, the user entered the ABORT command to terminate the 
task build by specifying the task name that the SPAWN LINK 
command executed. 


APPEND 


3.2 APPEND 


APPEND attaches records from one or more sequential files to the 
end of an existing sequential file. For details regarding 
sequential files, see the manual PRO/RMS-11: An Introduction, in 
the Tool Kit documentation set. 


Syntax 

APPEND[ /qualifier[s]] infile[,s] outfile 
qualifier 

Can be one or more of the following: 


/DATE:dd-mmm-yy 

/SINCE: dd-mmm-yy 

/THROUGH: dd-mmm-yy 

/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 

/EXCLUDE: filespec 

/NOWARNINGS 

/ SHARED 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


/DATA_TYPE 
VOC 

/MACY11 

/PRINT 
/TRANSFER_MODE 
/SUBMIT 

/ PROTECTION 
/OWNER 


infile 


Specifies the file or files to be appended to the output 
file. 


outfile 


Specifies the file to which the input files are appended. 


The output file must be an existing sequential file. The 
output file has the same version number after the APPEND 
command is executed as it had before the command was issued. 
The input files appear at the end of the output file in the 
order they were specified. 


APPEND 


No wildcards are permitted in output file specifications. 
There are no qualifiers for the output filespec. 


Although the output file must exist, it may be an empty 
file. 


Prompts 


File(s)? infile[,s] 
To: outfile 


Qualifiers 
/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the APPEND 
command to affect only files created by the value specified 
for /DATE. 


/SINCE: dd-mmm-yy 


The /SINCE qualifier specifies that you want the APPEND 
command to affect only files created on or since the value 
specified by /SINCE. 


/ THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the APPEND 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the APPEND command to affect only 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the APPEND 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the APPEND 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "x" 
wildcard. 


APPEND 


/{NO]WARNINGS 
The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
specified do not exist. 

/ SHARED 
The /SHARED qualifier specifies that you want other users to 
be able to access the file while you are performing the 
operation. 


Additional Qualifiers Available with PRO/DECnet 


Command Qualifiers 


/ LOG 
The /LOG qualifier specifies that the names of files 
appended and their sizes in blocks are to be displayed as 
the operation is performed. 

/PRINT 


The /PRINT qualifier specifies that the file will be queued 
to the line printer on the remote node for printing. The 
file will not be deleted by this operation. The file’s 
format must be compatible with the remote system. 

/SUBMIT 


The /SUBMIT qualifier specifies that the output ifle is a 
temporary file and will be submitted to the remote batch 


processor facility when copied. The file will be deleted 
after it is processed at the remote node. 


File Qualifiers 


/DATA_TYPE 


The /DATA_TYPE qualifier specifies how the data in the file 
is interpreted. /DATA_TYPE with APPEND requires either the 


ASCII or IMAGE argument. The default 1s IMAGE. /DATA_TYPE 
must be entered after the file specification in the command 
line. 


The ASCII argument transfers files in ASCII record mode and 
translates the records into an appropriate format for the 
remote system. You only need to use this argument when 
transferring text files to remote systems with file systems 
other than FILES-11 or RMS. File transfers to VAX/VMS~ and 
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PDP-11/RSX systems are more efficiently performed using the 
default, IMAGE. 


The IMAGE argument transfers files with their current format 
and attributes. If a remote system cannot interpret the 
file format, an error message will be displayed. If the 
file is an ASCII text file, you can recover by retrying with 
the ASCII argument. 


/MACY11 


The /MACY11 qualifier specifies that the input or output 
file on the remote TOPS-10 or TOPS-20 system is in MACY11 
format. This informs the remote DECsystem to handle the 
file appropriately when copying to or from the P/OS system. 
/MACY11 must be entered after the file specification in the 
command line. 


/TRANSFER_MODE 


The /TRANSFER_MODE qualifier specifies’ the method of 
packaging file data during a file transfer. This qualifier 
requires either the BLOCK or RECORD argument with the APPEND 
command. RECORD is the default. /TRANSFER_MODE must be 
entered after the file specification in the command line. 


The BLOCK argument transfers files in block mode, using 
blocks of 512-byte sizes. This is more efficient than using 
record mode, but should only be used with systems that 
Support FILES-11 or RMS-11, such as VAX/VMS, PDP-11/RSX, or 
PDP-11/RSTS/E RMS FAL. 


The RECORD argument transfers a file one record at a time. 
A record is a logical unit of data ina file. 


/ OWNER 
This qualifier specifies the UIC of the file. A UIC 
establishes the owner of a file. See the Tool Kit User’s 


Guide for a description of UIC. 
/ PROTECTION: code 
This qualifier specifies the protection code applied to the 


output file. See the description of the SET PROTECTION 
command for details on the code. 


ASSIGN 


3.3. ASSIGN 


This command creates a logical name and assigns an equivalence 
string to the specified logical name. An equivalence name can be 
a device name, another logical name, a file specification, or any 
other string. 


To specify the logical name table where you want to enter a 
logical name, use /USER, /SESSION, or /SYSTEM. I£ you do not 
explicitly specify a logical name table, the default is /SESSION. 


Syntax 

ASSIGN[ /qualifier[s]] equiv_name logical_name 
qualifier 

Can be one or more of the following: 


/USER 

/SESSION 

/OoYSTEM 

/FINAL 
/TRANSLATION_ATTRIBUTES 


equiv_name 


Defines the equivalence name to be associated with the 
logical name in the specified logical name table. The 
equivalence name string can contain from 1 EO 2) 
characters. If the equivalence name contains quotation 
marks, enclose the string in quotation marks and use_ two 
sets of quotation marks ("") in the places where you want a 
GuOtaALION. Mark: LO appedr-. 


Note that if you enclose an equivalence name string in 
quotation marks the case of alphabetic characters is 


preserved. 
logical_name 


Specifies the logical name string. The logical name string 
Can Contain. from.1 to 255 characters. ff the Logical name 
contains quotation marks, enclose the string in quotation 
marks and use two sets of quotation marks ("") in the places 
where you want a quotation mark to appear. 


Note that if you enclose a logical name string in quotation 
marks the case of alphabetic characters is preserved. 
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ASSIGN 


Prompts 


Equivalence Name? equiv_name 
Logical Name? logical_name 


Qualifiers 

/USER 
Places the logical name in the user logical name table. 
Logicals created in the user logical name table are deleted 
when you exit any application (including DCL). 


/ SESSION 


Places the logical name in the session logical name table. 
Session logical names are deleted when you logout of the 
system. If you do not explicitly specify a logical name 
table, the default is /SESSION. 


fOYSTEM 


Places the logical name in the system logical name table. 
All system users can access the logical name. 


System logical names are never deleted unless an explicit 
deassign logical operation is performed. 


/FINAL 
Indicates that the equivalence name string should not be 
translated iteratively; logical name translation should 
terminate with the current equivalence string. The /FINAL 
qualifier is synonymous with: 
/TRANSLATION_ ATTRIBUTES: TERMINAL 
/TRANSLATION_ATTRIBUTES:[(keyword[,...])] 
Specifies one or more attributes to modify a logical name 
string. The /TRANSLATION_ATTRIBUTES qualifer is positional 


and must be specified before the equivalence name. 


You can specify the following keywords for translation 
attributes: 


ASSIGN 


CONCEALED Indicates that the logical name is a concealed 


device name. If you specified the CONCEALED 
attribute, the logical name must be a device 
name of the form ddnnn: and the equivalence 


name must be-of the torm ..ddnnn:[(/ directory. |; 
The device name in the equivalence name must be 
present. The [directory.]. portion of the 
equivalence name is optional. 


TERMINAL Indicates that the equivalence name string 
Should not be translated iteratively; logical 
name translation should terminate with the 


current equivalence string. 


If you specify only one keyword, you may omit the 
parentheses. Only the attributes you specify are set. 


Examples 


S ASSIGN DW001:[CHARLES] CHARLIE: 
S PRINT CHARLIE: TEST. DAT 


The ASSIGN command associates the logical name CHARLIE with the 


device and directory DW001:[CHARLES]. Susequent references to 
the logical name CHARLIE: result in the correspondence between 
the logical name CHARLIE: and the disk and directory specified. 
The PRINT command queues a copy of the file 


DW001:{CHARLES]TEST.DAT to the default print queue. 
S ASSIGN DW001:[CHARLES] CHARLIE: /USER 


The ASSIGN command associates the logical name CHARLIE: with the 

directory name [CHARLES] on the device DW001: and makes the 

assignment in the user logical name table. 
S AS/TRANSLATION_ATTRIBUTES: CONCEALED _DW002:[CHARLES.] - 

S-PDOO1: 

S DIRECTORY PD001:[USERFILES] 


Directory PD1:[(USERFILES] 
28-JUN-85 11:20 


TEST .DAT os 27-JUN-85 17:21 


Total of 4.7/4. DLOcKS in. Ls fives 


The ASSIGN command associates the logical name PDOQO1: with the 
directory name [CHARLES] on the device Dw002. Subsequent 
references to the device PDOO1: result in the device and 


directory specified as being used as the MFD for all file 
operations. 


ASSIGN 


S ASSIGN/TRANSLATION_ATTRIBUTES: TERMINAL XX001: TEMP: 


The ASSIGN command associates the logical name TEMP: with the 
device xXxX001. Subsequent references to the logical TEMP: will 
result in the device xXxX001: being used without any futher 


translation attempts on the equivalence name XxX001:. 


ASSIGN/TASK 


3.4 ASSIGN/TASK 


ASSIGN/TASK reassigns the logical unit numbers (LUNs) of an 
installed task from one physical device to another. Thies 
reassignment overrides the static LUN assignments in the _ task’s 
disk image file. ASSIGN/TASK cannot change the LUNs of an active 
task. 


Syntax 
ASSIGN/TASK:taskname ddnnn: lun 
taskname 


Identifies the installed task whose LUN you want LO 
reassign. 


ddnnn: 


Specifies the device to which you want the LUN reassigned. 
This can be a physical device or logical device name. 


lun 

Specifies which LUN you want to reassign to the new device. 
Prompts 

Taskname? taskname 

Device? ddnnn: 

Logical. unit? lun 


BASIC 

3.5 BASIC 
BASIC invokes the PRO/Tool Kit BASIC-PLUS-2 compiler to begin a 
BASIC session. (Refer to the BASIC on RSX-11M/M-PLUS Systems 
manual and the BASIC Reference Manual for additional 
information. ) 
Syntax 

BASIC 


Prompts 


None 


CANCEL 


3.6 CANCEL 


CANCEL eliminates entries from the clock queue. Either the RUNS 
directive or the time-based forms of the RUN command place 
entries in the clock queue. CANCEL only affects pending entries 
in the clock queue and does not affect a task that is currently 
executing. 
Syntax 

CANCEL taskname 


taskname 


Is the name of the inactive, installed task entry that is to 
be deleted from the clock queue. 


Prompts 


Taskname? taskname 


CLEAR 


3.7 CLEAR 


This 


command clears the screen and optionally resets the terminal 


subsystem to an initial state. 


Syntax 


CLEAR [/qualifier] 


qualifier 


/RESET 


Prompts 


None 


Qualifier 


/RESET 


Emits a reset-to-initial-state (RIS) sequence, which 
initializes the Terminal Subsystem to default states and 
clears the screen. The RIS sequence is normally invoked 
whenever you power-up (boot) the Professional or reset the 
PRO/Communications terminal emulator. For further 
information, see the description of the RIS sequence in the 
Terminal Subsystem Manual. 


COBOL 


3.8 COBOL 


COBOL invokes the PRO/Tool Kit COBOL-81 compiler to compile COBOL 
language source files. 


NOTE 


Please refer to the language documentation for 
additional information. 


Syntax 

COBOL[/qualifier[s}] filespec 
qualifier 

Can be one or more of the following: 


/{NO]ANSI_FORMAT 
Jf (| NOVCHECK(.<arg 4 

[NO }]BOUNDS 

[NO ]PERFORM 

ALL 

NONE 
CODE? [| NOJCIS 
/{NO]CROSS_REFERENCE 
/{NO]DEBUG 
/{NO]DIAGNOSTICS[:filespec] 
FJINOJ“LIST(* £1 lespec] 
/NAMES : XX 
/{[NOJOBJECT{:f£ilespec] 
/{NO]OVERLAY_DESCRIPTION 
/{NO]SHOW: [NO]MAP 
/{NO]SKELETON 
/{NO]SUBPROGRAM 
/TEMPORARY: device 
/{NO]TRUNCATE 
/{NO]WARNINGS: [NO] INFORMATIONAL 


Filespec 


Specifies the source file to be input to the COBOL-81 
compiler. 


File input to the. COBOL=81 ‘compiler “must ‘contarm COBOL 
source code. File specifications must have filenames. The 
default file type is .CBL. 


COBOL 


Prompts 

File? filespec 
Qualifiers 
/{NO]ANSI_FORMAT 


The /ANSI_FORMAT qualifier specifies that the source file is 
in conventional (or ANSI) format. Conventional format has 
80-character lines with Area A beginning in character 
position. 8. 


The /NOANSI_FORMAT qualifier specifies that the source file 
is in terminal format, a DIGITAL-specified format that 
permits variable length lines with Area A beginning in 
Character position 1. 


The default is /NOANSI_FORMAT. 


/{NO]CHECK[ :arg] 
[NO]BOUNDS 
[NO ]PERFORM 
AG 
NONE 


The /CHECK and /CHECK:ALL qualifiers are equivalent--both to 
each other, and also to /CHECK:BOUNDS and /CHECK:PERFORM in 
combination. They add object code that checks the ranges of 
subscripts, indexes, and nested PERFORM statements at run 
time. 


The /CHECK:BOUNDS qualifier compares subscript and index 
ranges at run time against the ranges defined by 
corresponding OCCURS clauses. If any range is exceeded 
during program execution, COBOL-81 issues an error message. 


The /CHECK: PERFORM qualifier determines whether or not your 
program’s PERFORM statements are nested properly (if nested 
ac. salt). If cCOBOL-81 detects improper nesting during 
program execution, it 1ssSueS an error message. 


The /NOCHECK and /CHECK:NONE qualifiers are equivalent--both 


to each other, and also to /CHECK:NOBOUNDS and 
/CHECK:NOPERFORM in combination. They suppress all range 
checking. 


The /CHECK:NOBOUNDS qualifier suppresses range checking only 
for subscripts and indexes. 


COBOL 


The /CHECK:NOPERFORM qualifier suppresses range checking 
only for nested PERFORM statements. 


The qualifiers that suppress range checking reduce task size 
and improve program performance. 


The default is /CHECK {/CHECK:ALL). 
/CODE:[NO]CIS 


The /CODE:CIS qualifier tells the compiler to use CIS 
(Commercial Instruction Set) in the object code it produces. 


NOTE 


The Professional 300 Series computers do not have 
the Commercial Instruction Set. 


The /CODE:NOCIS qualifier tells the compiler not to use CIS. 


These qualifiers override the default for your system. They 
are used to develop programs that will execute on a 
different system than the one used for program development. 
For example, if your system has CIS, you use /CODE:NOCIS to 
compile a program that will run on a system without CIS. 


/{NO]CROSS_REFERENCE 


The /CROSS_REFERENCE qualifier causes the compiler to 
produce a list f116 and to.add “two cross-reference tables to 
the end of the list file: one for data-names and one _ for 
procedure-names. In each table, the names you use in your 
COBOL program are listed alphabetically. Opposite each name 
is a list of every line number in which that name occurs. A 
"D" after a number indicates the line in which you define 
the name. An asterisk (*) after a line number indicates a 
destructive reference, such as a value assignment to a 
data-name. 


The /NOCROSS_REFERENCE qualifier suppresses production of 
the cross-reference tables. 


The default 1s /NOCROSS_ REFERENCE. 

/{NO]DEBUG 
The /DEBUG qualifier indicates that you plan to include the 
COBOL-81 Symbolic Debugger in your task image. To Support 
the Symbolic Debugger, the compiler generates symbol 


information in the object module for all data-names and 
procedure-names in your program. 


Bee Ae: 


COBOL 


If you include the Symbolic Debugger in your program, you 
must also use the /DEBUG qualifier to the LINK command. 


The /NODEBUG qualifier suppresses generation of symbol 
information in the object module. 


The default is /NODEBUG. 
/(NO]DIAGNOSTICS[:filespec] 


The /DIAGNOSTICS qualifier creates a diagnostics file that 
contains the compiler diagnostic summary. If you do not 
append a file specification, the diagnostics file has’ the 
same filename as your source file, and the file type .DIA. 


The /NODIAGNOSTICS qualifier suppresses the creation of a 
diagnostics file. 


The default is /NODIAGNOSTICS. 
7 NOILIST [2 £1 Lespec |] 


The /LIST qualifier produces a list file which contains both 
the complete source code and any diagnostic messages. If 
you do not append a file specification, the list file has 
the same filename as the source file and has file type .LST. 


The /NOLIST qualifier suppresses production of a list file. 
The default is /NOLIST. 
/NAMES : XX 


The /NAMES:xx qualifier tells the compiler to use the _ two 
alphanumeric characters you specify as the PSECT kernel for 
your program. You wise ‘this ‘qualifier to ensure ‘unique 
identification for PSECT kernels when your task image uses 
both subprograms and segmentation. 


/{NOJOBJECT[:filespec] 


The /OBJECT qualifier produces an object module. If you do 
not append :filespec, the object module has the same 
filename as the source and the file type .OBJ. 


The /NOOBJECT qualifier suppresses production of an object 
module and its associated skeleton ODL file. (See the 
description of /[NO]SKELETON. ) 


COBOL 


The default is /OBJECT. 

/{NO]OVERLAY_ DESCRIPTION 
The /OVERLAY_DESCRIPTION qualifier produces two files--an 
indirect command file and an Overlay Descriptor Language 
file. 
The indirect command file has the same filename as_ the 
source andthe file type .CMD. It can be input to the Task 


Builder to create the task image. 


The Overlay Descriptor Language file has the same filename 


as the source and the file type .ODL. It contains pointers 
to certain support routines that must be included in your 
task image (tor example, system Support for file 
input/output). 


If you plan to use the LINK/C81 command to task-build your 
program, do not use the /OVERLAY DESCRIPTION qualifier 
(refer to Section 3.35 for a description of the LINK/C81 
command). LINK/C8i also creates a .CMD and an .ODL file, 
and cannot reference the .CMD and .ODL files created during 
program compilation. 


The /NOOVERLAY_DESCRIPTION qualifier suppresses production 
OF CMD: and «ODL Titles during program compa lation. 


The default is /NOOVERLAY_ DESCRIPTION. 
/{[NO]SHOW: [NO]MAP 
The /SHOW and /SHOW:MAP qualifiers are equivalent. They 


cause the compiler to produce a list file and to append two 
offset maps to the list file. One offset map refers to the 


Data Division and one to the Procedure Division. The 
compiler provides these maps for use with ODT (the On-Line 
Debugging Tool). Consult the IAS/RSX-11 ODT Reference 


Manual for more information. 


The /NOSHOW and /SHOW:NOMAP qualifiers are equivalent. They 
Suppress production of the offset maps. 


The default is /NOSHOW (/SHOW:NOMAP). 
/{NO]SKELETON 


The /SKELETON qualifier produces a skeleton ODL file, which 


Specifies the overlay structure for the object module. This 
file has the same filename as the source and the file type 
Meo te See 
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You cannot use the /SKELETON qualifier to override the 
/NOOBJECT qualifier. That is, an .SKL file cannot be 
produced when the .OBJ file is suppressed.: The /NOSKELETON 
qualifier suppresses production of the .SKL file. 


You cannot use the /NOSKELETON qualifier if you plan to 
task-build your program with the LINK/C81 command. LINK/C81 
assumes the presence of the .SKL file. Although the .SKL 
file is not strictly necessary for all programs, DIGITAL 
does not recommend that you suppress its production unless 
you are familiar with task-building alternatives to 
LINK/C81. 


The default is /SKELETON. 
/{NO]SUBPROGRAM 


The /SUBPROGRAM qualifier tells the compiler to treat the 
source file as a subprogram. You should use this qualifier 
only if the subprogram does not use parameters from the main 
program; that is, if it does not contain the Procedure 
Division USING header. 


The /NOSUBPROGRAM qualifier tells the compiler to treat’ the 
source aS a main program. 


The default is /NOSUBPROGRAM. 
/ TEMPORARY: device 


The /TEMPORARY qualifier tells the compiler to store the 
temporary work files it uses during program compilation on 
the device you specify. Since the default device is the 
System. ‘disk (SY). ~Has -qualitier 26 1Sef02.2f there. as 
little system disk space available. 


/{NO]TRUNCATE 


The /TRUNCATE qualifier tells the compiler to perform 
decimal truncation on the values of COMP data items. With 
decimal truncation, the maximum value the data item can 
contain depends on the item’s PICTURE character-string. 


The /NOTRUNCATE qualifier tells the compiler to perform 
binary truncation on the values of COMP data items. With 
binary truncation, the maximum value a COMP item can contain 
depends on its storage allocation. 


The default is /NOTRUNCATE. 
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/{NO]WARNINGS: [NO] INFORMATIONAL 


The /WARNINGS and /WARNINGS: INFORMATIONAL qualifiers are 
equivalent. They cause the compiler to issue informational, 
warning, and fatal diagnostics. 


The /NOWARNINGS and /WARNINGS:NOINFORMATIONAL qualifiers are 
equivalent. They suppress production of informational, 
warning, and fatal diagnostics. 


The default is /WARNINGS (/WARNINGS: INFORMATIONAL). 


CONTINUE 


3.9 CONTINUE 


CONTINUE resumes execution of a previously-suspended task. 
Nonprivileged users can continue tasks initiated from their own 
terminals. Privileged users can continue any suspended task. 
Syntax 

CONTINUE taskname 
taskname 

Is the name of the task to be restarted. 


Prompts 


Taskname? taskname 


3223 
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3.10 CONVERT 


CONVERT invokes the RMSCNV utility, which moves records from one 
Eile Co. -another. CONVERT reads: records. Erom an input “ile -and 
writes them to an output file. This conversion depends on _ both 
the organization (sequential, relative, or indexed) of the files, 
and qualifiers included with the CONVERT command. Refer to the 
RSX-11M/M-PLUS RMS-11 Utilities Manual for further information on 
the RMSCNV utility. 


Syntax 

CONVERT([ /qualifier[s]] input_file output_file 
qualifier 

Can be one or more of the following: 


/{NO]APPEND 
/{NO]FIXED_CONTROL 
/({NO]IDENTIFICATION 

/ INDEXED 

/KEY{(:n] 
/{[NO]LOG_FILE[:filespec] 
/{NO|]MASS_INSERT 

/MERGE 

/(NO]PAD[:[#]larg] 
/RELATIVE 

/[NO]REPLACE 

/ SEQUENTIAL 
/{NO]TRUNCATE 


inpue..tale 


Specifies the name of the file that is the source of records 
tO WANE Sucoue aM Le: CONVERT reads records sequentially, 
regardless of the organization of the input file. CONVERT 
accepts no wildcards. 


OUTPUT. Tike 


Specifies the name of the file to receive records from the 
input file. The default file organization for the output 
file is sequential. If the output file is not sequential, 
use the /RELATIVE or /INDEXED qualifier to indicate the 
organization. If the output file is to be -sequential, 
CONVERT can create the file; it need not exist prior to your 
entering the CONVERT command. CONVERT cannot create indexed 
or relative files; these must have been created prior to 
your entering the CONVERT command. Refer to the 


CONVERT 


RSX-11M/M-PLUS RMS-11 User’s Guide EOr additional 
information. The CONVERT command does not accept wildcards. 
Prompts 


Input file ? input_file 
Output file? output_file 


Qualifiers 
/{NO]JAPPEND 


Specifies that you want RMSCNV to append records to the end 
of an existing sequential file. If the output file is not 
sequential, RMSCNV ignores the qualifier. You cannot use 
both /APPEND and /REPLACE in the same command line. 


The default is /NOAPPEND, but the action taken depends. on 
the presence of the /REPLACE qualifier in the command line. 
If you specified /REPLACE, RMSCNV performs the replace 
Operation. If you did not specify /REPLACE, RMSCNV creates 
the next higher version of the file. 


This qualifier is the equivalent of the /AP switch in an 
RMSCNV command line. 


/{NO]FIXED_CONTROL 


The /FIXED_CONTROL qualifier directs RMSCNV_ to handle 


variable-with-fixed-control (VFC) format records in either 
the input file or the output file. If the fixed-control 
area of the input file and the output file are the same 
Size, RMSCNV performs a straightforward copy. See the 
RMS-11 documentation supplied with your system for. 
information on how RMSCNV handles other combinations. TE 


you include this qualifier and neither file specifies VFC 
records, RMSCNV terminates. 


This qualifier is the equivalent of the /WF switch in an 
RMSCNV command line. 


The default is /NOFIXED CONTROL. This means that if one of 
the named files contains VFC records, the fixed-control area 
of each record is ignored. That 1s, if the anput fite 
includes VFC records and the output file does not, only the 
variable portion of each record is written to the output 
file. If the output file includes VFC records and the input 
file does not, data is written only into the variable 
portion of each output record. 
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/{NO]IDENTIFICATION 


Requests that RMSCNV print its current version number’ and 
patch level on your terminal. See the RMSCNV documentation 
for more information. 


This qualifier is the equivalent of the /ID switch in an 
RMSCNV command line. 


The default is /NOIDENTIFICATION. 


/ INDEXED 


The /INDEXED qualifier informs RMSCNV that the output is of 
indexed organization. Regardless of their organization, all 
input files are read sequentially. 


RMSCNV reads each record from the input file, then applies 
the output file’s record format, that is, key placement 
within the record, to the data. If you do not specify the 
/KEY qualifier with a value, the key of reference is the 
primary key; otherwise, it is the key you specify. 


This qualifier is the equivalent of the /FO:IDX switch in an 
RMSCNV command line. 


J REY S| 


Indicates the key that establishes the order in which 
records are read sequentially from an indexed input file and 
written to the output file. mn can be from 0 through 9. The 
default is n=0 and indicates the primary key; n=1 1s the 
first alternate key; n=9 is the ninth alternate key. 


This qualifier is the equivalent of the /KR qualifier in an 
RMSCNV command line. 


/{[NO]LOG_FILE[:filespec] 
Directs RMSCNV to summarize processing ina log. If you do 
not include a filespec, the log appears on your terminal. 
If you name a file, that file will be created and written to 


by RMSCNV. The log includes the following elements: 


® The command string in RMSCNV format. This will not be 
the same as DCL format. 


® Copies of all error messages produced during execution. 
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@ An indication of any duplicate-key problems. If the log 
1S appearing on the terminal, the indication consists 
only of the following message: 


SOME DUPLICATE RECORDS NOT WRITTEN 


if the log is being written. to a file; RMSCNV -supplies 
the indicator DUP RCD= followed by the first 72 
characters of the record that could not be written. 


This qualifier is the equivalent of the /SL qualifier in an 
RMSCNV command line. 


The default is /NOLOG_FILE, meaning that only normal error 
messages appear on your terminal. 


/{NO]MASS_INSERT 


Directs RMSCNV to activate the RMS-11 mass insert I/0 
technique and then use sequential put operations to insert 
records into the output file. 


This is the equivalent of the /MA qualifier in an RMSCNV 
command line. 


The default for nonsequential file organization is 
/NOMASS_INSERT. 


/ MERGE 


Directs RMSCNV to copy records from the input file into’ the 
output file. Both files must be of the same organization. 


/{[NO]PAD[:[#]arg] 


Directs RMSCNV to pad records read from the input file to 
the output file’s record length before writing them to the 
file. If you specify the qualifier without an argument, the 
pad character is null. If you do not include the number 
Sign (#), the argument can be any printing ASCII character 
except: the number sign, question mark C2)2 OF 
commercial-at sign (@). If you include the number sign, nn 
can be an octal number from 0 through 377, representing the 
full ASCII character set. This enables you to use the three 
excluded characters as pad characters by specifying 43 for 
+, 77 for ?, and 100 for @. 
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Use this qualifier only when the output file specifies 
fixed-length records. 


This qualifier is the equivalent of the /PD qualifier in an 
RMSCNV command line. 


/RELATIVE 
The /RELATIVE gualifier informs RMSCNV that the output file 
is OF relative organization. Regardless of their 


organization, all input files are read sequentially. 


The /RELATIVE qualifier is the equivalent of the /FO:REL 
qualifier in an RMSCNV command line. 


RMSCNV reads records from the input file and writes them 
into successive record cells of the output file, beginning 


with cell 1. If RMSCNV encounters a cell containing a 
record, it terminates with an error message. All records 
written to that point are in the output file. You should 
examine the two files to determine how far the processing 
went. 


/{NO]REPLACE 


The /REPLACE qualifier directs RMSCNV to supersede an 


SXisting Sequential file, RMSCNV replaces a file in the 
output account with the same filename, type, and version 
number. You cannot use /REPLACE and /APPEND in the same 


command line. 


The /REPLACE qualifier is the equivalent of /SU in an RMSCNV 
command line. 


The default 1s /NOREPLACE, but the default action depends on 
whether the command line includes an /APPEND or not. If you 
specify /APPEND, RMSCNV performs the append operation. dite 
you do not specify /APPEND, RMSCNV creates the next higher 
Version “OL. The tale. 


/ SEQUENTIAL 
The /SEQUENTIAL qualifier informs RMSCNV that the output 
file is of sequential organization. Regardless of their 
organization, all input files are read sequentially. The 


default output file organization for RMSCNV is Sequential. 


This qualifier is the equivalent of the /FO:SEQ qualifier in 
an RMSCNV command line. 
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If you do not specify either the /APPEND or /REPLACE 
qualifier, and the output file is sequential, the output 
file need not exist before you issue the CONVERT command. 


If the output file does not exist, RMSCNV creates an output 
file with the record attributes of the input file. RMSCNV 
then reads records from the input file and writes them 
sequentially into the new output file. 


If the output file already exists, and the command does not 
include the /APPEND qualifier, RMSCNV creates the next 
higher version of the file. RMSCNV then reads records’ from 
the input file and writes them sequentially into the new 
version of the output file. 


If the output file exists and you specify the /REPLACE 
qualifier, RMSCNV reads records from the input file and 
writes them sequentially into the output file, starting with 
the beginning of the file. 


If the output file exists and you specify the /APPEND 
qualifier, RMSCNV reads records from the input file and 
writes them into the output file, starting with the record 
position following the last record already in the file. 


/[NO]TRUNCATE 


Directs RMSCNV to truncate records read from the input file 
to the output file’s record length before writing them into 
the output file. The trailing bytes of the record are 
truncated. 


The default is /NOTRUNCATE. If you do not specify /TRUNCATE 
and the input records are too long, RMSCNV terminates. 
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3.11 COPY 


This command creates a sequential file copy of one or more 
sequential files, or of records with either indexed or relative 
file organization. 


Syntax 

COPY[/qualifier[s]] input_filespec[,s] output_filespec 
qualifier 

Can be one or more of the following: 


/{[NO] CONTIGUOUS 

/ REPLACE 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 

/EXCLUDE: filespec 
/{NO]WARNINGS 
/PRESERVE_DATE 
/ALLOCATION:n[. ] 
/NONEW_VERSION 
/OVERLAY 

/ SHARED 

/ OWN 


With PRO/DECnet DCL extensions, the following qualifiers are 
also available: 


/CONCATENATE 
/DATA_TYPE 
JOG 

/MACY11 
/NEW_VERSION 
/NOSPAN 

/PRINT 

/SUBMIT 
/TRANSFER_MODE 
/OWNER 
/PROTECTION 


COPY 


input_filespec 
Specifies the input file or files to be copied. 
You must have READ access to a file to copy it. 


Multiple filespecs, separated by commas, are accepted. ik 
you specify multiple input files, they will be concatenated 
in a single output file in the order that you specify them. 


output_filespec 


Specifies a single output file to which the input file or 
files is copied. 


You can change the name, type, and version number of the 
file when you enter this parameter. Wildcards in the place 
of the name and the type leave the name and type unchanged. 
If you use a wildcard in either of these fields, you must 
use a wildcard in both. 


COPY always creates the output file. For example, if you 
ctype: 


COPY EPILEI LIS. FLLEZ. Ls 


and FILE2 already exists, COPY will create a new version of 
the file one higher than the existing version. If FILE2 
does not already exist, COPY will create a file with the 


name FILE2 and extension .LIS. If you specify a version 
number for the output file field, then a file of that 
version number is created. If such a file already exists, 


the operation fails. 


Wildcards are acceptable for output files if the destination 
is another directory. If you have multiple input files and 
use wildcards for the output file, you create multiple 
output files, each with the name and type of the 
corresponding input file. 


You can send copies to devices as well as to directories. 


You can also use the COPY command to create multiple copies 
of the same file with the same or different names. 


Prompts 


From? input_filespec[,s] 
TO2 Output. fi1lespec 


COPY 


Qualifiers 

/{NO]CONTIGUOUS 
Specifies that the output file must be contiguous. If this 
qualifier is not used, then only files that are already 
contiguous remain contiguous when copied. 
The default is /NOCONTIGUOUS. 

/REPLACE 
If the output file has the same name, type, and version 
number as an already existing file at the destination, the 


first file is deleted and the file you have sent replaces 
it. The name, type and version number stay as they were. 


/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the COPY command 
to affect only files created by the value specified for 
/DATE. 


/SINCE: dd-mmm-yy 


The /SINCE qualifier specifies that you want the COPY 
command to affect only files created on or since the value 
specified by /SINCE. 


/THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the COPY 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the COPY command to atrect only tiles 
created within that range. 


/TODAY 


The /TODAY qualifier specifies that you want the COPY 
command to affect only files created on the same day as the 
command is issued. 
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/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you don’t want COPY to 
affect certain files. The filespec argument to /EXCLUDE can 
contain wildcards, but the filespec must contain a version 
number, either explicitly or as the "*" wildcard. 


/{NO]WARNINGS 


The /[NO]JWARNINGS qualifier specifies that the "No such 
file" error messages should not be displayed when the input 
files specified do not exist. 


/ALLOCATION:n[. ] 


The /ALLOCATION:n[.] qualifier specifies that n blocks of 
contiguous space be allocated for the new copy of the file. 
Unless you append the optional decimal point, the value n is 
interpreted as an octal value. 


/NONEW_VERSION 


The /NONEW_VERSION qualifier prevents the version number 
from being automatically incremented when a file is copied. 
You must specify this qualifier when you copy all versions 
of a particular filename and type. 


/OVERLAY 


The /OVERLAY qualifier causes the contents of the input file 


or files to be copied into the output file. Whatever is 
currently in the output file is destroyed, although the file 
ID remains unchanged. The output file must exist before you 


issue the command. 
/PRESERVE_DATE 


The /PRESERVE_DATE qualifier specifies that you want’ the 
output file to have the same creation date as the input 
file. By default, today’s date is the creation date of the 
output file. 


/ SHARED 


The /SHARED qualifier specifies that you want other users to 
be able to access the file while you are copying it. 


/OWN 


COPY 


The /OWN qualifier changes the ownership of the file being 
copied to the destination directory. After execution, both 
directories own their respective copies of the file. If you 
do not specify /OWN, the original UIC owns both copies of 
the file. 


Additional Qualifiers Available with PRO/DECnet 


Command Qualifiers 


/CONCATENATE 


The /CONCATENATE qualifier specifies that the output file 
Should be a single file that contains all of the input files 
in the order specified. If wildcards are used in the input 
file specification, the files will be concatenated in random 
order. 


/LOG 
The /LOG qualifier specifies that the names of files copied 
and their sizes in blocks are to be displayed as the 
operation is performed. 

/PRINT 
The /PRINT qualifier specifies that the file will be queued 
to the line printer on the remote node for printing. The 
file will not be deleted by this operation. The file’s 
format must be compatible with the remote system. 

/SUBMIT 


The /SUBMIT qualifier specifies that the output file is a 
temporary file and will be submitted to the remote batch 
processor facility when copied. The file will be deleted 
after it 1s processed at. the remote node. 


File Qualifiers 


/DATA_TYPE 


The /DATA_TYPE qualifier specifies how the data in the file 


is interpreted. With the COPY command, the DATA TYPE 
qualifier takes either the ASCII or IMAGE argument. The 
default is IMAGE. /DATA_TYPE must appear after the file 


Specification in the command line. 
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The ASCII argument transfers files in ASCII record mode and 
translates the records into an appropriate format for the 
remote system. You only need to use this argument when 
transferring text files to remote systems with file systems 
other than RMS. File transfers to VAX/VMS and PDP-11/RSX 
systems, which use RMS, are more efficiently performed using 
the default, IMAGE. 


The IMAGE argument transfers files with their current format 
and attributes. If a remote system cannot interpret that 
format, an error message will be displayed. If the file is 
an ASCII text file, you can recover by retrying with the 
ASCII argument. 


/MACY11 


The /MACY11 qualifier specifies that the input or output 
file on the remote TOPS-10 or TOPS-20 system is in MACY11 
format. This informs the remote DECsystem to handle the 
file appropriately when copying to or from the P/OS system. 
/MACY11 must appear after the file specification in the 
command line. 


/NEW_VERSION 


The /NEW_VERSION qualifier specifies that the output files 
be created with a version number higher than any existing 
files of the same name in the directory. /NEW_VERSION must 
appear after the file specification in the command line. 


/NOSPAN 


The /NOSPAN qualifier specifies that the output file be 
created with records that do not span block boundaries. 
Normally, only files that already have records that do not 
span block boundaries remain as such when copied. /NOSPAN 
must appear after the file specification in the command 
line. 


/TRANSFER_MODE 


The /TRANSFER_MODE qualifier specifies the method of 
packaging file data during a file transfer. For the COPY 
command, the TRANSFER_MODE qualifer takes the argument 
AUTOMATIC, BLOCK, Or -RECORD. AUTOMATIC is the default. 
/TRANSFER_MODE must appear after the file specification in 
the command line. 
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The AUTOMATIC argument causes DCL to select either BLOCK or 
RECORD after checking the file capabilities at the remote 
node. If you have problems transferring files with the 
AUTOMATIC argument, try specifying either BLOCK or RECORD. 
The BLOCK argument transfers files in block mode, using 
blocks of 512-byte sizes. This is more efficient than using 
record mode, but should only be used with systems that 
Support RMS-11, such as VAX/VMS, PDP-11/RSX, or 
PDP-11/RSTS/E RMS FAL. 


The RECORD argument transfers a file one record at a time. 
A record is a logical unit of data ina file. 


/OWNER: [UIC] 
The /OWNER qualifier specifies the UIC of the output file. 
A UIC establishes the owner of a file. See the Tool Kit 
User’s Guide for a description of UIC. 

/ PROTECTION: code 
This qualifier specifies the protection code applied to the 


output. Lite. See the description of the SET PROTECTION 
command for details on the code. 


3.12 CREATE 


CREATE creates a sequential file and enables 


directly into the 


editor. 
Syntax 
CREATE filespec 


filespec 


CREATE 


file from your 


you 
terminal 


to tCype. text 
without using an 


Specifies the name of the file to be created. 


As soon as the command is entered, 


line. The 
into the file. 


file 1s open for input. 
When you have finished entering text, 


down a 
Any text you type goes 
type a 


the cursor moves 


CTRL/Z to close the file. 


If you want to create an empty sequential file, 
the CT RL/Z first. 


Simply enter 


If you use CTRL/U when creating a sequential file, the text 


on the line is eliminated, but not the line itself. In 
other words, CTRL/U leaves a blank line behind when it 
deletes a line. CTRL/U, CTRL/R, and the DELETE key are the 


only editing facilities available to when 


sequential files at the terminal. 


you creating 


Prompts 
File? 


With PRO/DECnet DCL 
available: 


/CONTIGUOUS 
FEOG 

/MACY11 
/NEW_VERSION 
/NOSPAN 
/{NO]WARNINGS 
/PRINT 
/REPLACE 

/ PROTECTION 
/OWNER 
/SUBMIL! 


Filespec 


extensions, the 


following qualifiers are 


CREATE 


With PRO/DECnet, the CREATE command creates a file from records 
you type. In other words, when you press <DO> after entering the 
CREATE command, all subsequent keystrokes are entered into a file 
that you named with the CREATE command. To close and store the 
File, press <CTRL/Z>. 


Command Qualifiers 
/LOG 


The /LOG qualifier specifies that the names of files created 
and their sizes in blocks are to be displayed as the 
operation is performed. 


/NOWARNINGS 


The /NOWARNINGS qualifier specifies that the "No such file" 
error messages Should not be displayed when the input files 
specified do not exist. 


/PRINT 


The /PRINT qualifier specifies that the file will be queued 
to the line printer on the remote node for printing. The 
File will not be deleted by this operation. The file’s 
format must be compatible with the remote system. 


/SUBMIT 


The /SUBMIT qualifier specifies that the output file is a 
temporary file and will be submitted to the remote batch 
processor facility when copied. The file will be deleted 
after it 1S processed at the remote node. 


File Qualifiers 
/CONTIGUOUS 


The CONTIGUOUS qualifier specifies that the output file must 
be contiguous. /CONTIGUOUS must appear after the file 
specification in the command line. 


/MACY11 


The /MACY11 qualifier specifies that the input or output 
File on the remote TOPS-10 or TOPS-20 system is in MACYi1 
format. This informs the remote DECSystem to handle _ the 
file appropriately when copying to or from the P/OS system. 


CREATE 


/MACY11 must appear after the file specification in the 
command line. 


/NEW_VERSION 


The /NEW_VERSION qualifier specifies that the output files 
will be created with a version number higher than any 
existing files of the same name 1 a the directory. 
/NEW_VERSION must appear after the file specification in the 
command line. 


/NOSPAN 


The /NOSPAN qualifier specifies that the output file will be 
created with records that do not span block boundaries. 
Normally, only files that already have records that do not 
Span block boundaries remain as such when copied. /NOSPAN 
must appear after the file specification in the command 
line. 


/REPLACE 


With the /REPLACE qualifier, if the output file has the same 
name, type, and version number as an already existing file 
at the destination, the first file is deleted and the file 
you have sent replaces it. The name, type, and version 
number stay as they were. /REPLACE must appear after the 
file specification in the command line. 


/OWNER: [UIC] 


This qualifier specifies the UIC of the file. A UIC 
establishes the owner of a file. See the Tool Kit User’s 
Guide for a description of UIC. 


/PROTECTION: code 
This qualifier specifies the protection code applied to the 


output file. See the description of the SET PROTECTION 
command for details on the code. 


CREATE/DIRECTORY 
3.13 CREATE/DIRECTORY 


CREATE/DIRECTORY creates a User File Directory (UFD) on a 
FILES-11 volume and enters the UFD into the volume’s Master File 
Directory (MED). 


Syntax 
CREATE/DIRECTORY [device: ] [dirspec] [qualifier[s]] 
device: 
Specifies the name of the device on which you want the 
directory created. The default is SyY0:. If you do not 


specify a device or volume name, a directory is created on 
the default volume, SyY0:. 


dirspec 


Is the name of the directory, enclosed in square brackets, 
thal you “want “co “create. You must specify at least the 
dirspec parameter. 


qualifier 
Can be one or more of the following: 


/NOWARNINGS 
/OWNER_UIC: [UIC] 


Prompts 
Directory? [device: ][dirspec] 
Qualifiers 
/NOWARNINGS 
Supresses error messages that can result from the command. 
/OWNER_UIC: [UIC] 
Specifies the User Identification Code (UIC) of the 
directory’s owner. A UIC establishes the protection status 


of the directory. See the Tool Kit User’s Guide for details 
on UICs and file protection. 


CREATE/DIRECTORY 


By default, the directory is owned by the issuer of this 
command. You can specify any UIC as the owner by using the 
/OWNER_UIC qualifier. However, a non-privileged user cannot 
always create files in a directory that is owned by another 
ULC: 


DEASSIGN 
3.14 DEASSIGN 


This command deletes a logical name assignment created through 
the use of the ASSIGN command or DEFINE command. 


Syntax 


DEASSIGN[/qualifier[s]] [logical_name] 


qualifier 
Can be any combination of the following: 


/USER 

/ SESSION 
/SYSTEM 

/ALL 


logical_name 
Is the name of a unique logical name. If you created the 


logical name using quote characters, you must use quote 
characters in the logical name to perform the DEASSIGN. 


Prompt 
Logical name? Logical name 
Qualifiers 
By default, if you do not specify any of the qualifiers /USER, 


/SESSION, or /SYSTEM, P/OS performs the operation in the session 
logical name table. 


JRGL 
Indicates that all logical names in the specified logical 
mame table be deassigned. 

/SESSION 


Limits the search for the logical to the session logical 
mame table. This is the default. 


DEASSIGN 


/SYSTEM 


Limits the search for the logical 
table. You should not delete 
names defined in this table. See 


for a list of these logical names. 


FUSER 


Limits the search for the logical 
table. 


to the system logical name 
any P/OS standard logical 
the Tool Kit User’s 


to the user 


logical 


Guide 


name 


DEBUG 


3.15 DEBUG 


This command executes a debugger that you have built into your 
task. The command sets the T-bit in the task’s Processor Status 
Word (PSW). To build a debugger into your task, you must specify 
the /DA qualifier on the PAB command line you use to build your 
task. 
Syntax 

DEBUG taskname 


taskname 


Is the name of the task that you want to debug. 
Prompt 


None 


DEFINE 


3.16 DEFINE 


This command creates a logical name and assigns an equivalence 
string to the specified logical name. An equivalence name can be 
a device name, another logical name, or a file specification. 

To specify the logical name table where you want to enter a 


logical name, use /USER, /SESSION, or /SYSTEM. If you do not 
explicitly specify a logical name table, the default is /SESSION. 


Syntax 

DEFINE[/qualifiers] logical_name equiv_name 
qualifiers 

Can be one or more of the following: 

/USER 

/ SESSION 

PSISTEM 

/FINAL 

/TRANSLATION_ATTRIBUTES: [(keyword[,...])] 


logical_name 


Specifies the logical name string. The logical name string 


can contain from 1 to 255 characters. If the logical name 
contains quotation marks, enclose the string in quotation 
marks and use two sets of quotation marks ("") in the places 


where you want a quotation mark to appear. 


Note that if you enclose a logical name string in quotation 
marks the case of alphabetic characters is preserved. 


equiv_name 


Defines the equivalence name to be associated with the 
logical name in the specified logical name table. The 
equivalence name string can contain from 1 to 220 
characters. If the equivalence name contains quotation 
marks, enclose the string in quotation marks and use two 
sets of quotation marks ("") in the places where you want a 
quotation mark to appear. 


Note that if you enclose an equivalence name string in 
quotation marks, the case of alphabetic characters 1s 
preserved. 


DEFINE 


Prompts 


Logical Name? logical_name 
Equivalence Name? equiv_name 


Qualifiers 
/USER 


Places the logical name in the user logical name table. 
Logicals created in the user logical name table are deleted 
when you exit any application (including DCL). 


/SESSION 


Places the logical name in the session logical name table. 
Session logical names are deleted when you logout of the 
system. If you do not explicitly specify a logical name 
table, the default is /SESSION. 


/OYSTEM 


Places the logical name in the system logical name table. 
All system users can access the logical name. 


System logical names are never deleted unless an explicit 
deassign logical operation is performed. 


/FINAL 


Indicates that the equivalence name string should not be 
translated iteratively; logical name translation should 
terminate with the current equivalence string. The /FINAL 
qualifier is synonymous with: 


/TRANSLATION_ATTRIBUTES : TERMINAL 
/TRANSLATION_ATTRIBUTES:[(keyword[,...])] 
Specifies one or more attributes that modify a logical name 
String. The /TRANSLATION_ATTRIBUTES gqualifer is positional 


and must be specified before the logical name is specified. 


You can specify the following keywords for translation 
attributes: 


DEFINE 


CONCEALED Indicates that the logical name is a concealed 


device name. If you specified the CONCEALED 
attribute, the logical name must be a device 
mame of the form ddnnn: and the equivalence 


mame must be of the form -_ddnnn:{directory.]. 
The device name in the equivalence name must be 
present. The [directory.] portion ona the 
equivalence name is optional. 


TERMINAL Indicates that the equivalence name string 
Should not be translated iteratively; logical 
name translation should terminate with the 


current equivalence string. 


If you specify only one keyword, you may omit the 
parentheses. Only the attributes you specify are set. 


Examples 
S DEFINE CHARLIE: DW001:[CHARLES] 
S$ PRINT CHARLIE:TEST.DAT 
The DEFINE command associates the logical name CHARLIE: 
with the directory name [CHARLES] on the device DWOQ0O1. 
Subsequent references to the logical name CHARLIE: result 
in the correspondence between the logical name CHARLIE: and 
the disk and directory specified. The PRINT command queues 
a copy of the file DW001:[CHARLES]TEST.DAT to the default 
print queue. 
S DEFINE CHARLIE: DW001:[CHARLES] /USER 
The DEFINE command associates the logical name CHARLIE: 
with the directory name [CHARLES] on the device DW001: and 


makes the assignment in the user logical name table. 


S$ DEFINE/TRANSLATION_ATTRIBUTES:CONCEALED PDO001: - 
S-_DW002:[CHARLES. ] 


S DIRECTORY PD001:[USERFILES ] 


Directory PD1:[USERFILES] 
28-JUN-85 11:20 


TEST .DAT 4 ZI=JUN=85 27224 
Total of 4.74.2. brOCKS- im 1s. tales 
The DEFINE command associates the logical name PDOQQ1: with 


the di reccory name [CHARLES ] on the device DWO0O02. 
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Subsequent references to the device PDOO1: result in the 
device and directory specified as being used as the MFD for 
all file operations. 


S DEFINE/TRANSLATION_ATTRIBUTES: TERMINAL TEMP: XX0OO1: 


The DEFINE command associates the logical name TEMP: with 
the device xXxX001. Subsequent references to the logical 
TEMP: will result in the device XX001: being used without 
any further translation attempts on the equivalence name 
XXOU1S.< 


DELETE 


3.17 DELETE 


DELETE removes a file specification entry from a directory, 
releases the corresponding storage space occupied by those files, 
and causes any data in the corresponding file or files to _ be 
inaccessible. 


Syntax 

DELETE[/qualifier[{s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/ LOG 

/QUERY or /CONFIRM 

/DATE:dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 

/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yyy 
/ TODAY 

/EXCLUDE: filespec 

/{NO]WARNINGS 


fFilespec 


Specifies the file or files to be deleted. You must specify 
the name, file type, and version number fields of the 
filespecs you want to delete. Device and directory fields 
default to your current device and directory. DELETE 
accepts wildcards in any field except the device field. You 
need not supply a file type to delete a file with a null 


file type. 
Prompts 

Files(s)? filespec[,s] 
Qualifiers 


/ LOG 


Specifies that a list of the files deleted be displayed on 
your terminal. 


DELETE 


/QUERY or /CONFIRM 


Specifies that you want to decide which files should be 
deleted on an individual basis. Each file that is specified 
in the command is named. You may enter one of four 
characters: 


Y - Deletes file named and goes on to next file. 
N - Does not delete file named and goes on to next 


file. 

G - (Go) Deletes the file and goes on to delete all 
other files specified. 

QO - (Quit) Does not delete the file and exits the 


DELETE command. No more files are deleted. 


Remember that you can specify files by default or wildcard. 
If you do not specify a version number, /QUERY is the 
default. 


/DATE:dd-mmm-yy 
The /DATE qualifier specifies that you want the DELETE 
command to affect only files created by the value specified 
for /DATE. 

/SINCE:dd-mmm-yy 
The /SINCE qualifier specifies that you want the DELETE 
command to affect only files created on or since the value 
specified by /SINCE. 

/THROUGH: dd-mmm-yy 
The /THROUGH qualifier specifies that you want the DELETE 
command to affect only files created on or before the value 
specified by /THROUGH. 

/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the DELETE command to affect only 
files created within that range. 

/ TODAY 
The /TODAY qualifier specifies that you want the DELETE 


command to affect only files created on the same day as the 
command is issued. 


DELETE 


/EXCLUDE:filespec 


The /EXCLUDE qualifier specifies that you want the DELETE 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 


/{NO]WARNINGS 


The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
Specified do not exist. 


DELETE/DIRECTORY 


3.18 DELETE/DIRECTORY 


This command deletes an empty directory. An error message 
appears if you attempt to delete a directory that is not empty. 
Syntax 


DELETE/DIRECTORY [device:][dirspec] 


device: 
Is an optional device name, such as DW1: or SY:. If you do 
not specify a device name, the system searches the current 
default device for the directory to delete. See the Tool 


Kit User’s Guide for further details on device names. 
dirspec 


Is a directory name enclosed in square brackets. An example 
is [USERFILES]. 


Prompts 
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Directory? [device: ]{dirspec] 


DIBOL 


3.19 DIBOL 


This command invokes the PRO/Tool Kit DIBOL compiler to 
DIBOL source code files. 


NOTE 
Please refer to the language documentation for 


additional information. 


Syntax 
DIBOL[/qualifier[s]] filespec[,s][/qualifier[s] ] 
qualifier 


Can be one or more of the following: 


LIST[{:filespec] 
OBJECT[:filespec] 
/{[NOJOPTIMIZE 
/PAGE_SIZE:number (D:system default) 
/{NO]STANDARD 
/([NO]SHOW 
/{NO]WARNINGS 


filespec 
Is the name of a DIBOL source code file. 
NOTE 
If you want to reference a universal library 


containing source code modules, use the following 
format: 


DIBOL[/qualifiers[s] filespec[,s][{/qualifier[{s] libr_spec/LIBR 


libr_spec 


Is the name of the universal (default) library. 


DIBOL 


/GLBR 
Signals the DIBOL compiler that libr_spec is a universal 
(default) library. You may include only one such library in 
each compilation. 

Prompts 
File(s)? filespec[{,s] 

Qualifiers 

/[NO]BUILD 
/BUILD causes the build option to be invoked automatically 
after the compilation phase. This qualifier creates .CMD 
and .ODL files for direct input to the Professional 
Application Builder (PAB). 

/{NO]CROSS_REFERENCE 
The /CROSS_REFERENCE qualifier causes the compiler CO 
produce a list file and to add across reference table to 
the end of the listing file. 

/{NO]DEBUG 
/DEBUG includes extra information for the DIBOL debugger. 
The default is /NODEBUG which prevents the inclusion of this 
information. 

/(NO]JLIST[:filespec] 
/LIST causes the DIBOL to output a file with the same name 
as the source listing. /LIST creates this output. You may 
change the name of this output file by typing: 
/LIST:new_filespec 
Refer to NOTE in /[NO]OBJECT. 

/(NO]OBJECT([:filespec] 


/OBJECT creates an object module with the same name as the 


source La sceing and is the default value. JOBJECT: 
new_filespec creates an object file with a filename 
different than the source filename. /NOOBJECT suspends the 
creation of an object file. (When you list more than one 


source file on the command line and you specify /OBJECT, 
DIBOL creates an object file with the name of the first 
source file listed.) 


DEBUG 


NOTE 
Use of the qualifiers /NOOBJECT and /NOLIST allows 


the DIBOL command to check for errors. 


/PAGE_SIZE:n 


The /PAGE_SIZE qualifier specifies the number of lines per 
page in the listing file. 


/OPTIMIZE 


/OPTIMIZE causes DIBOL to optimize the object file. The 
default is /NOOPTIMIZE which does not produce an optimized 
object file. 

/{NO]STANDARD 


/STANDARD flags all occurrences of P/OS (RSX-11M-PLUS) 
extensions to DIBQOb=63, <Tnis Ss -the: detault« 


POHOW SEALS Lipo ay f) 


Table 3-1 shows the value of arg. In the table, the letter 
"D" indicates the default argument for this qualifier. 


Table 3-1: Argument Values for /SHOW Qualifier 


Argument Default Description 

ALL Shows everything. 

NONE Shows only source (nothing else). 

COND D Shows non-compiled conditionals. 
NOCOND Does not show non-compiled conditionals. 
INCLude D Shows included files. 

NOINCL Does not show included files. 

TABLes Shows symbol and label tables. 

NOTABL D Does not show symbol and label tables. 
SOURCe D Shows DIBOL source. 

NOSOUR Does not show DIBOL source. 


DIBOL 


/{[NO]WARNINGS 


/WARNINGS displays accompanied by /LIST) 
warning messages produced by the DIBOL compiler; /WARNINGS 
is the default value. 


/NOWARNINGS suppresses the display 
(listing) of warning messages. 


(Or "prints Ls 
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3.20 DIFFERENCES 


This command invokes the Compare (CMP) utility (refer to Chapter 
5), which compares two ASCII (text) files, line by line, to 
determine if parallel records (lines) are identical. After this 
comparison, DIFFERENCES produces a listing of any differences 
between the two files. 


Syntax 

DIFFERENCES[/qualifier[s]] input_filel input_file2 
qualifier 

Can be one or more of the following: 


/CHANGE_BAR[:n] 
/ILGNORE: (arg{,s]) 
BLANK LINES 
COMMENTS 
FORM FEEDS 
SPACING 
TRAILING BLANKS 
/LINES:n 
/NONUMBERS 
/OUTPUT: filespec 
fou | ea) 


input_filel 


Specifies the first of two files to be compared. The 
filename must be included, and the default file type is 
.MAC. 


input_file2 


Specifies the second of two files to be compared. The 
filename must be included, and the default file type is 
.-MAC. 

Prompts 
Filespeci? input. tibet 
Filespec2? LMDUL tite? 


DIFFERENCES 


Qualifiers 
/CHANGE_BAR[ :nnn] 


Specifies that the output consists of a listing of infile2 
with change bars applied to each line in infile2 that does 
not have a corresponding line in infilel. The nnn argument 
is the number of the ASCII character to be used for the 
change bar. The default is 041, the exclamation point (!). 
The following are codes for some commonly used ASCII 
characters: 


041 
043 
044 
052 
053 
074 
076 
O77 
074 


——- YJ VAN + + TNH = 


J ILGNORE? Garg 4S) ) 


BLANK LINES 
COMMENTS 

FORM FEEDS 
SPACING 
TRAILING BLANKS 


Specifies that you want certain defaults to be ignored in 
making the comparison. Without the /IGNORE qualifier, the 
comparison is strictly line-by-line. If you specify only 
one argument, you do not need the parentheses. If you 
specify more than one argument, enclose them in parentheses 
and separate them with commas (,). 


The default is to include all these factors in the 
comparison. 


The BLANK LINES argument specifies that blank lines are _ to 
be excluded from comparison. The default is to include 
blank lines in the comparison. 


The COMMENTS argument specifies that comments, that is, text 


preceded by a semicolon (;) not be included in the 
comparison. Otherwise, comments are compared like all other 
text. 


DIFFERENCES 


The FORM_FEEDS argument specifies that lines beginning with 
a single form feed character (CTRL/L) are to be excluded 
from the comparison. The default is to include such lines 
in the comparison. 


The SPACING argument specifies that any sequence of blank 
and tab characters is to be interpreted as a single blank 
for the comparison. This argument is useful when comparing 
source files that differ only in their spacing. The output 
listing includes blanks and tabs as they are found in the 
input files, but the blanks and tabs are ignored. The 
default is to compare sequences of blanks and tabs like any 
other characters. 


The TRAILING BLANKS argument specifies that all blanks 
following the last nonblank character in the line be ignored 
in the comparison. The default is to compare trailing 
blanks like all other characters. If you specify both 
TRAILING_BLANKS and COMMENTS in your /IGNORE qualifier, any 
blanks preceding a semicolon (;) are also ignored. 


The DCL DIFFERENCES command does not have quite the same 
defaults as CMP, the File Compare Utility, which DIFFERENCES 
invokes. Specify /LGNORE: (BLANK_LINES, FORM_FEEDS ) to 
duplicate the CMP defaults for blank lines and form feeds. 
Other CMP defaults need not be specified. | 


/LINES:n 
Specifies that n lines must be identical before a match is 
recognized. The default value for nis three identical 
lines. 


/{NO]NUMBERS 


/NONUMBERS specifies that lines in the output file not be 


preceded by line numbers. The standard output listing 
automatically includes line numbers. Line numbers) start 
with 1 in increments of one. All lines are numbered, 


including blanks. 
/OUTPUT: filespec 
Specifies that the output listing be written to the file 


named in the qualifier. Normally, this output appears on 
your terminal. 


DIFFERENCES 


fobPt sau. 


Specifies that the output listing take the form of an SLP 
indirect command file. When you include this qualifier, the 
output listing is an SLP indirect command file that makes 


infilel identical to infile2. The optional au argument, 
preceded by a Coon, is a 1- through 8-character 
alphanumeric audit trail symbol. For more information on 


the Source Language Input Program (SLP), see Chapter 10. 


DIRECTORY 


3.21 DIRECTORY 


DIRECTORY displays information for an individual file or a group 
of files. 


Syntax 
DIRECTORY[/format-qual][{/other-qual[{s]] [filespec[,s]] 
format-qual 


Controls the appearance of the directory list and can be one 
of the following: 


/FULL 

/BRIEF 
/FREE[ddnnn: | 
/ SUMMARY 
/ATTRIBUTES 


other-qual 


Modifies the list of files by creation date or exclusion and 
may be one or more of the following: 


/DATE:dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 

/EXCLUDE: filespec 

/OUTPUT: 

/NOWARNINGS 


With PRO/DECnet DCL extensions, the following qualifier is also 
available: 


/WIDTH:n 

filespec[,s] 
Specifies the file or files for which information should be 
displayed. Tf you do not supply a filespec, the complete 
default directory is displayed. 


You can supply one or more filespecs, separated by commas, 
to display directory information on the files you name. 


DiRECTORY 


You can use wildcards in place of any filespec field except 
the device field. If you do not supply a version number, 
only information on the most recent versions is displayed. 
However, if you do not supply a file type, a null file type 
is assumed. If you do not know the file type, use a 
wildcard. 


You can display another directory by supplying the directory 
name in this field. You can also specify device names in 
tne form ddnnny: in this field. 


If you name files in two directories, you should name files 
for the default directory first. If you name files from 
another device or directory first, the defaults are 
canceled. 

Prompts 
None 

Qualifiers 


Qualifiers are in two groups: 


1. Format qualifiers control the appearance or the 
directory. 


2. Other qualifiers modify the list of files by creation 
date or exclusion. 


If you do not supply a qualifier from the format-qual list, 
the display is in standard format, which shows: the 
filename, type, and version number; the number of blocks the 
file occupies; and the date and time of creation. 


If you do not include any qualifier from the other-qual 
list, the display includes all files that otherwise qualify. 


Format Qualifiers 

/BRIEF 
Specifies that the display give filenames, types, and 
version numbers only. 

/FULL 
Specifies that the complete directory entry be displayed, 
including file ID number, blocks used and allocated, the 


owning UIC, protection status of the file, in addition to 
all the information in the standard display. 
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/ SUMMARY 


Specifies that the display give only the total number of 
blocks allocated and used for the specified files. If you 
give no filespecs in the command, the display shows’ the 
total blocks allocated and used for the default directory. 


/FREE [ddnnn: ] 


Specifies that the display give the free space and number of 
free file headers on the default device or a specified 
device. 


/ATTRIBUTES 


Displays the Record Management Services (RMS-11) attributes 
of a file or files. This display includes filename and 
type, creation date and time, file organization, protection 
Status, allocation information, last access date and time, 
record format, record size, primary and alternate key 
definitions for indexed files, and bucket size for indexed 
and relative files. This qualifier invokes the RMS-1i1 DSP 
UGLY, 


NOTE 
This display is produced for any file you specify in 


a DIRECTORY command, whether or not the file is an 
RMS-11 file. 


Some display information may not be meaningful for non-RMS 
files. 

Other Qualifiers 

/DATE:dd-mmm-yy 
The /DATE qualifier specifies that you want the DIRECTORY 
command to affect only files created by the value specified 
for /DATE. 

/SINCE:dd-mmm-yy 
The /SINCE qualifier specifies that you want the DIRECTORY 


command to affect only files created on or since the value 
specified by /SINCE. 
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/THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the DIRECTORY 
command to affect only files created on or before the value 
Specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the DIRECTORY command to affect only 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the DIRECTORY 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the DIRECTORY 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "x" 
wildcard. 


/OUTPUT: filespec 


The OUTPUT qualifier specifies that the output of the 
DIRECTORY command be placed in a file having the file 
specification you supply. 


/{NO]WARNINGS 


The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
specified do not exist. 


Additional Qualifiers Available with PRO/DECnet 
Command Qualifiers 


/WIDTH:n 


The /WIDTH qualifier specifies the width of the display for 
the default and /FULL format displays only. The default 
value is 72. At least one field is always displayed per 
line, even if that field exceeds the maximum width 
specified. 


DISMOUNT 


3.22 DISMOUNT 


This command marks the volume mounted on the specified device to 
be logically off-line and disconnected from the file system. 


Syntax 
DISMOUNT device: [volumelabel] 
device: 
Is the name of the device on which the magnetic medium 
containing the volume is currently mounted. This argument 
can be in the form ddnnn:, or it can be a logical name 
previously assigned to the device by the MOUNT command. 
volumelabel 
Is the name of the volume. If the volume currently mounted 
in devname does not match the volume label you specify, the 


system does not dismount the device. 


Prompt 


» ad eee oe Ceo Ps ee es ee | 
Device? daevice: [volLumelabei ] 
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3.23 DUMP 

DUMP displays or prints the contents of a file or volume in 
ASCII, hexadecimal, octal, or decimal format. This command 
invokes the File Dump (DMP) Utility. (Refer to Chapter 6.) 
Syntax 


DUMP[/qualifier[{s]] filespec 
qualifier 
Can be one or more of the following: 


/ASCII 

/BASE_ADDRESS:n:m 
JBUOCKS Ine M 

/BYTE 

/DECIMAL 

/FILE: file-number:sequence-number 
/FILE_HEADER[:[NO]FORMATTED ] 
/HEADER 

/HEXADECIMAL 
/IDENTIFICATION 

/LOGICAL BLOCK 

/ LONGWORD 

/ LOWERCASE 

/NUMBER[ :1] 

/OCTAL 

/OUTPUT: file-name 

/RADIX_50 

/RECORD 

/WORD 


Filespec 

Is the file specification to be displayed (dumped). 
Prompts 

File? [i165 pec 
Qualifiers 


JASCIT 


/ASCII specifies that the data should be dumped one byte at 
a time in ASCII mode. This qualifier displays the full DEC 
Multinational Character Set. The control characters (0-37) 
are printed as a circumflex ("), followed by the alphabetic 
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character corresponding to the character code plus 100. For 
example, bell (code 7) is printed as “G (code 107). The 
control characters from 200 (octal) through 240 (octal) are 
displayed as Chr, where Chr is the control character + 100 
(OC tal) 


Lowercase characters (140-177) are printed as a percent sign 
(3), followed by the corresponding uppercase character 
(character code minus 40), unless the /LOWERCASE qualifier 
is specified. The /ASCII and /OCTAL qualifiers are mutually 
exclusive when dumping bytes. 


/BASE_ADDRESS:n:m 


This qualifier specifies a two-word base block address (the 
initial base address is 0,0), where n is the high-order base 
block address (octal), and mis the low-order base block 
address (octal). The address may also be specified in 
decimal by using a period after the number. All future 
block numbers specified by the /BLOCKS qualifier will be 
added to this value to obtain an effective block number. 
This qualifier is useful for specifying block numbers that 
exceed 16 bits. For example: 


/BASE_ADDRESS:1:0 


specifies that all future block numbers will be relative to 
65536 (decimal) (200000 octal). Also, the following clears 
the base address: 


/BASE_ADDRESS:0:0 


When the /BASE_ADDRESS appears in a command line, no blocks 
are dumped. The only result of the command line is to set 
the base address. 


NOTE 


The following pertains if you run DUMP directly as a 
Wed Laity. 


once this qualifier ts Specified, it remains in effect. until 
Lt 1s used again to set a new base address. The 
/BASE_ADDRESS qualifier would be the /BA:n:m qualifier 
(refer to Chapter 6 for further information). 
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/BLOCKS:n:m 


Specifies the range of blocks to be dumped, where n is the 
First block and mis the last block. The values of n and m 
must not exceed 16 bits. In file mode only, the /BLOCKS:n:m 
qualifier is not required. If the /BLOCKS:n:m qualifier is 
not specified, DMP will dump all blocks of the specified 
file, relative to the current base address. 


If /BLOCKS:n:m is specified in file mode, it specifies the 
range of virtual blocks to be dumped. If /BLOCKS:n:m is 
specified as /BLOCKS:0 file mode, no virtual blocks are 
dumped. This is useful for dumping only the header portion 
of the file (see /HEADER). The /BLOCKS:n:m qualifier and 
the /RECORD qualifier are mutually exclusive. 


The /BLOCKS:n:m qualifier is a required parameter in device 
mode. When used in device mode, it specifies the range of 
logical blocks to be dumped. 


The value n represents the block number of the first block 
dumped. Successive blocks are labeled with a block number 
one higher than the preceding block number. The dump will 
continue until the block labeled m is dumped. 


/BYTE 


Specifies that the data be dumped in octal byte format. 


/DECIMAL 


Specifies that the data be dumped in decimal word format. 


/FILE: file-number:sequence-number 


In file mode, the file number can be used instead of a 
filename as a file specification for input. 


/FPILE_HEADER[:[NO]FORMATTED ] 


This qualifier is an optional parameter used in file mode. 
In addition, this qualifier has two options. FORMATTED, the 
default, causes a FILES-11 formatted dump of the header. 
NOFORMATTED specifies an unformatted octal dump. An octal 
dump occurs when DUMP is used on non-FILES-11 headers. Tf 
specified, the /HEADER[:[NO]FORMATTED] qualifier causes the 
file header as well as the specified or implied portion of 
the file to be dumped. 


DUMP 


/HEADER 


Specifies the format for data blocks that have the FILES-11 
header structure. Other blocks are output as an unformatted 
octal dump. 

/HEXADECIMAL 


Specifies that the data be dumped in hexadecimal byte 


format. Note that a hexadecimal dump reads from right to 
left. (See also the /LONGWORD and /WORD qualifiers.) 
/IDENTIFICATION 


Causes DMP’s version to be identified. This qualifier may 
be specified on a command line by itself at any time. 


/LOGICAL BLOCK 


Requests logical block information for a file. The starting 
block number and a contiguous or noncontiguous indication 
for the file are displayed. 


/ LONGWORD 


Specifies that the data be dumped in hexadecimal double-word 
format. 


/ LOWERCASE 


Specifies that the data should be dumped in lowercase 
characters. 


/NUMBER[ :n] 


Specifies a memory dump and allows control of line numbers. 
Line numbers are normally reset to zero whenever a block 
boundary is crossed. The /NUMBER[:n] qualifier allows lines 
to be numbered sequentially for the full extent of the file, 
that is, the line numbers are not reset when block 


boundaries are crossed. The optional value (:n) specifies 
the value of the first line number. The default is Q. The 
/NUMBER[:n] qualifier is used with the output file 


specification. 


DUMP 


/OCTAL 


Specifies that the data should be dumped in octal format in 
addition to other formats specified. rf no tormat 
qualifiers are specified, the default is octal. The /ASCII 
qualifier and the /OCTAL qualifier are mutually exclusive 
when dumping bytes. 


/RADIX_50 


Specifies that data be dumped in Radix-50 format words. 


/ RECORD 
Specifies that data be dumped a record at a time (rather 
than a block at a time). The data format is determined by 
setting any of these format qualifiers: /ASCII, /DECIMAL, 


/HEXADECIMAL, /LONGWORD, /RADIX50, or /WORD. 


The largest record that DUMP can process is 512 (decimal) 
bytes. 


The /RECORD qualifier and the /BLOCK qualifier are mutually 
exclusive. 


/ WORD 


Specifies that the data be dumped in hexadecimal word 
format. 


EDIT OR EDIT/EDT 


3.24 EDIT OR EDIT/EDT 


EDIT starts an interactive editing session with the EDT editor to 
create or modify a file. 


Syntax 

EDIT([/qualifier[s]] filespec 
qualifier 

Can be one or more of the following: 
/{NO]COMMAND[:filespec] 
/([NO]JOURNAL[:filespec] 
/(NOJOUTPUT[:filespec] 
/{NO]RECOVER 
[NO]READ_ONLY 


Vi 
filespec 
Is the name of an existing file or the name of a file to be 
created. You must specify a filename, but the file type may 
be null. For example, the command: 
EDIT filename 
causes EDT to edit filename. ; 
Prompts 
File? Cfilespec 
Qualifiers 
/[NO]COMMAND[:filespec] 
Controls whether an EDT initialization file is read by EDT 
before editing begins. These files contain commands that 
alter the default setup for EDT, such as custom line-mode 
commands and change-mode key definitions. 
The default is /COMMAND:LB:[1,2]EDTSYS.EDT. If you use this 
qualifier and EDTINI.EDT or some other file you name does 


not exist, EDT issues no error message and continues with 
the editing session. 


EDIT OR EDIT/EDT 
If you do not want to use LB:[{1,2]EDTSYS.EDT, use the 
/NOCOMMAND qualifier. 
/({[NO]JOURNAL[:filespec] 


Controls whether EDT creates a journal file for the editing 


session. The default is to create a journal file with a 
filename the same as that of the input file with the type 
sJOUs You can specify a different name by including a 


filespec. 


The journal file consists of all editing commands and text 


entered during the session. If the editing session ends 
abnormally, such as through a system crash, or your 
inadvertently typing three cCTRL/ZS in succession, the 
journal file is saved. In such a case, you invoke EDT 


again, with the same command line as before plus the 
/RECOVER qualifier. Your editing session is repeated and 
all your editing is restored. If the editing session ends 
normally, the journal file is deleted. 


If you specify /NOJOURNAL, no journal file is created and no 
recovery is possible. 


/([NO]JOUTPUT[:filespec] 


If you do not specify this qualifier, the default is to 
create a file of the same name and type as the input file 
with a version number one higher than the input file. LE 
the file is new, EDT creates version number 1. You can 
alter the name of the output file by including a filespec 
with the /OQUTPUT qualifier. Otherwise, the qualifier need 
not be included. 


Tf you specify /NOOUTPUT, you cannot exit EDT without 
including a filespec in your EDT EXIT command. 


/[{NO]READ_ONLY 


Specifies whether you want simply to read the file or to 
edit it. If your command line includes /READ_ONLY, you can 
use the full facilities of EDT, but you cannot exit without 
including a filespec in your EDT EXIT command. Normally, 
you would use the EDT QUIT command if you had = specified 


/READ_ONLY. The /READ_ONLY qualifier 1s equivalent to a 
combination of /NOOUTPUT and /NOJOURNAL. You can use 
/READ_ONLY to look at files to which you have no write 
access. 


EDIT OR EDIT EDT 


The default is /NOREAD_ONLY, which need never be specified. 


/{NO]RECOVER 


Specifies whether EDT reads commands from a journal file 
prior to starting the editing session. With a journal file, 
your editing session can be restored if interrupted by a 
system crash or other problem. 


The default is /NORECOVER, which need never be specified. 


The /RECOVER qualifier requests EDT to open the input file 
and then read EDT commands and text from the file with the 
same filename as the input file and the file type .JOU. The 
command line with /RECOVER added to it must be identical to 
the command line that initiated the original failed editing 


session. This means that ai <you. Specifived «an EDT 
initialization file, you must specify the same file in the 
/RECOVER command Line. If you specified a name for the 


journal file other than infile.JOU, you must include the 
/JOURNAL qualifier with the appropriate filespec. 


If journaling was not enabled on the original command line, 
you cannot recover the editing session. 


EDIT/PROSE 


3.25 EDIT/PROSE 


EDIT/PROSE invokes the PROSE editor from DCL. 
NOTE 
This section only describes the DCL command that 


accesses the PROSE editor. For further 


information on PROSE: you. should -Curn to the .Prose 
User’s Guide. 


Syntax 

EDIT/PROSE/qualifier filespec 
qualifier 

/OUTPUT: filespec 


filespec 


Is the name of an existing input file that PROSE will edit 


or a new file spec that PROSE will first create and then 
edit. 


NOTE 
Whenever you leave a PROSE editing session, you 
cannot discard your edits from that session. If 


you do not want the output file, you have _ to 
delete it after exiting the editing session. 


Prompts 
File? filespec 
Qualifier 


OUTPUT: tilespec 


Causes EDIT/PROSE to name the output file with a different 
filename than the input filename. 


EDIT /SLP 


3.26 EDIT/SLP 


This command invokes the Source Language Input Program (SLP), 
which is an editor designed for maintaining and updating source 
files. (Refer to Chapter 10.) 
Syntax 

EDIT/SLP[/qualifier[{s]] filespec 
qualifier 

Can be one or more of the following: 

/{NO]AUDIT[:arg] 


POSITION:n 
SIZE:n 


/(NO]CHECKSUM[ :arg] 

/(NOJLIST[: filespec] 

/(NOJOUTPUT[:filespec] 

/{NO]REPORT 

/{NO]TAB 

/{[NO]TRUNCATE[ :n] 
fFilespec 


Is the name of the source program to be updated by SLP. 
Prompts 

File? filespec 
Qualifiers 


/{NO]AUDIT([:(arg[s])] 
POSITION:n 
SIZE:n 


Controls whether the output file includes an audit trail, 
and optionally allows you to specify the location and size 
of the audit trail. You can specify one or both of these 
values. If you specify only one, you can omit the 
parentheses, but the parentheses are required syntax if you 
specify both POSITION and SIZE. Separate the two arguments 
within the parentheses by a comma (,). 


The POSITION: argument sets the starting position of the 


audit. Trail. The value of n can be from 0 through 132, 
representing the column at which the first character in the 
audit trail is to appear. This value is rounded up to the 


a1) 


EDIT/SLP 


next highest tab stop. The default is to start the audit 
trait wat column: 20. Note that this default causes audit 
trails of more than a single character to wrap around when 
displayed on standard video terminals. 


The SIZE: argument sets the length of the audit trail. The 
value of n can be from 0 through 14. The default is an 
audit trail of 8 characters. The audit trail itself is 
defined from within SLP. See Chapter 10. 


/ | NO] CHECKSUM sarg] 


Controls whether a checksum is calculated for the SLP 
commands. If you specify checksum without an argument, SLP 
calculates the checksum value and prints it on your 
terminal. If you specify an argument, SLP calculates the 
checksum and compares it to what you have specified. If the 
numbers differ, a warning message is displayed, but the 
execution of SLP is not interrupted. 


The default is /NOCHECKSUM. 
/{NO]LIST[:filespec] 


The /LIST qualifier creates a listing of a file with line 
numbers. If you do not give a filespec, the default 
filespec is filename.LST. 


The default is /LIST. /NOLIST Suppresses creation of the 
basting fide. 


/{NOJOUTPUT[:filespec] 


Use this qualifier to change the name of the output file. 
The default output filespec is the same name and type as the 
input file and a version number one higher than the highest 
existing version of the file. If you do not want to 
override this default, you do not need this qualifier. 


The /NOOUTPUT qualifier suppresses creation of an output 
file. 


/{NO]REPORT 


Controls whether line truncations that result from audit 
trails are reported. If you specify /REPORT, you receive 
warning messages on your terminal and the affected lines are 
marked with a question mark (?) in place of the period (.) 
in the line number in the listing file. 


EDIT SGP 


The default is /NOREPORT. 
/{NO]TAB 


Controls whether SLP replaces tabs or spaces at the end of 
each record: containing an audit-.tralli, Lf you specify /TAB, 
tabs are inserted. If you specify /NOTAB, Spaces are 
inserted. The default is /NOTAB. 


/(NO]TRUNCATE[:arg] 
The TRUNCATE qualifier requests SLP to truncate each record 


in the input file when it creates the output file. This 
qualifier allows you to delete an audit trail from ae file 


previously updated with SLP. If you specify /TRUNCATE 
without a number, SLP truncates input records at_ the 
beginning position of the audit trail. If you specify a 


number, SLP truncates the records beginning at the column. 
The value of n can be from 0 through 132. 


The default is /NOTRUNCATE. 


EXIT 


3.27 EXIT 
Invoking this command, or pressing the EXIT key, causes you _ to 
exit PRO/Tool Kit. 
You should not exit PRO/Tool Kit if any tasks are still active. 
This includes active tasks submitted to background mode by the 
SPAWN command. (Refer to Section 2.4.) You should either allow 
all tasks to finish, or you should abort them. 
Syntax 

EXIT 


Prompts 


None 


3-78 


PIX 


3.28 FIX 


This command loads and locks a task into its partition. 
Subsequent requests for running the task are serviced more 
quickly because the task is memory-resident and does not have to 
be loaded from the disk before it can run. 

Fixed tasks remain physically in memory even after they exit. 
Therefore, they do not have to be reloaded when a request is made 
to run them. (Note that reexecuting fixed tasks is not always 
practical; to reexecute, the task must initialize all impure data 
and LUN assignments at run time.) Only a REMOVE command can free 
the occupied memory partition. 

Note the following requirements: 

o You must install a task before you f1ix it. 

Oo You cannot f1x a task whose name is in the form ...xxx or 
RRO OS This is because the copy of the task with that form 
of name is a nonexecutable, prototype task. 

o You cannot fix an active task. 

o You should not fix a checkpointable task because doing so 
makes the task noncheckpointable. 

See also the INSTALL command with the /FIX qualifier. 
Syntax 

FIX taskname [/qualifier] 
taskname 

Is the task or region to £1x in memory. 


qualifier 


/REGION 
/READONLY_SEGMENT 


Prompt 


Taskname? taskname 


FIX 


Qualifier 
/REGION 


Indicates that the task to be fixed is a region, such as a 
read-write common. 


/ READONLY_SEGMENT 


Fixes only the read-only segment of a multiuser task. 


FORMAT 


3.29 FORMAT 


This command sets up a hard disk so that that it 1S recognizable 
as a FILES-11 volume by its controller. Once you have formatted 
a disk, you can then use the INITIALIZE command to initialize it. 
Normally, the P/OS installation procedure formats the system 
disk. However, to connect additional hard disks to a 
Professional you must format each one by invoking the FORMAT 
command. 
Syntax 

FORMAT[/qualifier] device: 
qualifier 

/{NO]CONFIRM 
device: 

Is the name of the device on which the magnetic medium 

containing the volume is currently mounted. This argument 


can be in the form ddnnn[:], or it can be a logical name 
created with the ASSIGN or DEFINE command. ; 


Prompt 
Device? device: 

Qualifier 

/(NO]CONFIRM 
The /NOCONFIRM qualifier specifies that P/OS should not 
verify that the volume is already in FILES-11 format. The 
/CONFIRM qualifier asks you to verify the format request if 


the volume is already in FILES-11 format. The /CONFIRM 
qualifier is the default. 


FORTRAN 
3.30 FORTRAN 
FORTRAN invokes the PRO/Tool Kit FORTRAN-77 compiler 
FORTRAN language source files. 
NOTE 
Please refer to the language documentation 
additional information. 
Syntax 
FORTRAN([/qualifier[s]] filespec[,s] 
qualifier 
Can be one or more of the following: 
/{NO]CHECK 
/CONTINUATIONS:n 


/{NO]DEBUG 
/{NO]DLINES 


/LDENTIFICATION 
/(NO]I4 
/{NO]LIST[:filespec] 
/{NO]MACHINE_CODE 
/{NO]MAP 
/{(NOJOBJECT[:f1lespec] 
/{[NO]OPTIMIZE 
/ {NO ]SHAREABLE 
/SOURCE 3 
/{[NO]STANDARD:arg 
ALL 
NONE 
SOURCE 
SYNTAX 
/([NO]TRACEBACK: arg 
ALL 
BLOCKS 
LINES 
NAMES 
NONE 


/WORK_FILES:n 


EO 


Lor 


compile 


FORTRAN 


filespec 
Is the name of the FORTRAN source file. 
Prompts 
File(s)? filespec[,s] 
Qualifiers 
/{NO]CHECK 


The /CHECK qualifier specifies that you want the compiler to 
check that all array references are within bounds. 


The default is /NOCHECK. 


/CONTINUATIONS:n 


The /CONTINUATIONS qualifier specifies the maximum number of 
continuation lines permitted in the code. The value of n 
can be from 0 through 99. The default is 5. 


/|NO]DEBUG 


Specifies that the compiler is to provide symbol table 
information for use by the PRO/TOOL KIT FORTRAN-77 symbolic 
debugger. When you use the /DEBUG command qualifier, you 
should also use the /NOOPTIMIZE command qualifier. /NODEBUG 
is the default. 


/{NO]DLINES 


The /DLINES qualifier specifies that lines with a "pb" 
Character in column 1 are to be compiled. The default is 
/NODLINES, meaning these lines are treated as comment lines. 
Use this feature for debugging. 


/ IDENTIFICATION 


The /IDENTIFICATION qualifier causes the compiler to print 
its identification and version number on your terminal. 


/[NO]14 


The /14 qualifier causes a two-word default allocation for 
integer variables. The default is /NOI4, meaning the 
compiler causes a single-word allocation for any integer 
variables not given an explicit length specification. 


FORTRAN 


/(NOJLIST[ stilespec] 


Specifies whether a compiler listing should be generated. 
The default is /NOLIST, meaning no compiler listing is 


generated. 


If you do not supply a file specification for 


this 


qualifier, the listing has a filename derived from the name 


of the first source file in the FORTRAN command with 


the 


file type .LST. If you want the listing to have a different 
name, supply the name as an argument to the /LIST qualifier. 
If you do supply a name, the listing file appears in your 


directory but is not printed on the printer. 


The /LIST qualifier behaves ina different manner depending 
on whether it iS given as a command qualifier or a filespec 
qualifier. If /LIST:LP: is used as a command qualifier, 
the listing file is placed in your directory and printed on 


the printer. If /LIST is used as a filespec qualifier, 


the 


listing file appears in your directory but 1s not printed on 


the printer. If /LIST is used as a filespec qualifier, 
listing file takes the name of that file. 


NOTE 


The /MACHINE_CODE, /MAP, and /SOURCE, qualifiers 
all affect the contents of the compiler listing 
file. 


/{NO]MACHINE_CODE 
The /MACHINE_CODE qualifier specifies that you want 


compiler listing to include binary machine code 
diagnostics. The default 1s /NOMACHINE_CODE. 


the 


the 
and 


/MACHINE_CODE implies /LIST. You do not need to include the 
/LIST qualifier unless you want to use it to establish a 


name for the listing file different from any of 
filenames included in the compilation. 


the 


The /MACHINE_CODE qualifier behaves in a different manner 
depending on whether it is given as a command qualifier ora 
filespec qualifier. If /MACHINE_CODE is used aS a. command 


qualifier, the listing file is placed in your directory and 
printed on the printer. If /MACHINE_CODE is’ used a 
filespec qualifier, the listing file appears in your 
directory but is not printed on the printer. If 


/MACHINE_CODE is used as a filespec qualifier, the listing 


file takes the name of that file. 


FORTRAN 


/{NO]MAP 


The /MAP qualifier specifies that you want the compiler 
listing to include a storage map and diagnostics. 


/MAP implies /LIST. You do not need to include the /LIST 
qualifier unless you want to use it to establish a name for 
the listing file different from any of the filenames 
included in the compilation. 


The /MAP qualifier behaves ina different manner depending 
on whether it is given as a command qualifier or a filespec 
qualifier. If /MAP is used aS a command qualifier, the 
listing file is placed in your directory and printed on the 
printer. If /MAP is used as a filespec qualifier, the 
listing file appears in your directory but is not printed on 
the printer. If /MAP is used as a filespec qualifier, the 
listing file takes the name of that file. 


/(NOJOBJECT[:filespec] 


Determines whether or not an object module is generated by 
the compiler. The default 1s OBJECT; whlen does create a 
module. The default name of the object file created by 
FORTRAN is the last-named source file with the file type 
.OBJ. If you want the object file to have a different name, 
supply the name as an argument to the /OBJECT qualifier. 


/NOOBJECT specifies that no object module is created. You 
can use the /NOOBJECT qualifier to get a compiler listing 
file to check for errors without generating object code. 


/{NO]JOPTIMIZE 


Controls whether the compiler optimizes the compiled program 
to generate more efficient code. 


Use /NOOPTIMIZE in conjunction with the /DEBUG qualifier to 
link a P/OS FORTRAN-77 program with the debugger so that 
variables always contain their updated values. 


/[NO]SHAREABLE 


The /SHAREABLE qualifier states that you want the compiler 
to generate pure code and pure data sections as read-only. 
This takes advantage of code sharing in multiuser tasks on 
P/OS. 


FORTRAN 


/ SOURCE 


The /SOURCE qualifier specifies that you want the compiler 
listing to include the source code. 


/SOURCE implies /LIST. You do not need to include the /LIST 
qualifier unless you want to use it to establish a name for 
the listing file different from any of the filenames 
included in the compilation. 


The /SOURCE qualifier behaves in a different manner 
depending on whether it is given as a command qualifier or a 
filespec qualifier. If /SOURCE is used aS a command 
qualifier, the listing file is placed in your directory and 
printed on the printer. If /SOURCE is used as a filespec 
qualifier, the listing file appears in your directory but is 


not printed on the printer. If /SOURCE is used as a 
filespec qualifier, the listing file takes the name of that 
file. 
/{NO]STANDARD:arg 

ALL 

NONE 

SOURCE 

SYNTAX 


The /STANDARD qualifier directs the compiler to look in your 
source code for extensions to ANSI standard (X3.9-1978) 
FORTRAN at the full-language level. If the compiler finds 
extensions, re flags them and produces) informational 
diagnostics. 


The ALL argument produces informational diagnostics for all 
detected extensions. 


The NONE argument produces no informational diagnostics. 


The SOURCE argument produces informational diagnostics for 
lowercase letters and tab characters in the source code. 


The SYNTAX argument is the same as /STANDARD with no 
argument. 


The default is /NOSTANDARD. 


/([NO]TRACEBACK: arg 
ALL 
BLOCKS 
LINES 
NAMES 
NONE 


FORTRAN 


/TRACEBACK controls the amount of extra code included in the 
compiled output for use by the OTS during error traceback. 
This code is used in producing diagnostic information and in 
identifying which statement in the FORTRAN source program 
caused an error condition to be detected during execution. 


The ALL argument states that error traceback information is 
to be compiled for all source statements, and function and 
Subroutine entries. 


The LINES argument is the same as ALL. 


The BLOCKS argument states that traceback information is_ to 
be compiled for subroutine and function entries and initial 
statements in sequences called blocks. This is the default. 


The NAMES argument states that traceback information i1is_ to 
be compiled only for subroutine and function entries. 


The NONE argument states that no traceback information is to 
be produced. 


/WORK_FILES:n 


The /WORK_FILES qualifier specifies the number of temporary 
on-disk files you want used during the compilation. The 
argument n can range from 0 through 3; the default is 2. 
Increasing the number of work files increases the maximum 
possible size of your program but decreases the speed of 
compilation. 


HELP 


3.31 HELP 


HELP displays information about the commands and utilities. 
Syntax 

HELP| /quailitier] [topic }iscs 
qualifier 

Can be one or more of the following: 

/OUTPUT: filespec 

/FILE: filespec 

/tilename 

/ LOCAL 


EODICiu:8 


Are up to four optional topics, separated by spaces, for 
which you want help. 


Prompts 

None 
Qualifiers 
/OUTPUT: filespec 


Permits you to name an output file where the requested help 
text is to be saved. The default is /OUTPUT:TI:. 


/FILE:filespec 


Specifies any file where help text is located. Li “you. ido 
not give a complete file specification, the defaults are 
LB:({[1,2]filename.HLP. 


/ftLilename 


Specifies that the help text begins with 
LB:[{1,2]filename.HLP. 


/ LOCAL 


Specifies that the help text is in the file HELP.HLP in the 
default directory on the default device. 


INITIALIZE 


3.32 INITIALIZE 


This command deletes all existing files on a volume and imparts 
the standard FILES-11 file structure. INITIALIZE can also 
optionally check for bad blocks. Note that the volume must _ be 
formatted (see the FORMAT command) prior to being initialized. 


Syntax 


INITIALIZE[/qualifier[s]] device: volumelabel 
qualifiers 

/{NO]BAD_BLOCKS 

/ CHECKPOINT SPACE sn 

/{NO]CONFIRM 


device 


Is the name of the device on which the magnetic medium 
containing the volume is currently mounted. This argument 
can be in the form ddnnn[{:], or it can be a logical name 
previously assigned to the device. 


volumelabel 


re the Tabel that. mames the volume atter inatialsazation. It 
can be from 1 to 12 characters long. 


Prompts 


Device? device 
Volume name? volumelabel 


Qualifiers 

/{NO]BAD_BLOCKS 
/BAD_BLOCKS, the default, performs a check for bad blocks on 
the volume you are initializing. If any bad blocks are 
found, P/OS will not use them for storing information. Lt 
you specify /NOBAD_BLOCKS, P/OS does not search for bad 
blocks on the volume. 


/CHECKPOINT_SPACE:n 


Allows you to control the size of a system checkpoint file 
on the volume being initialized. 


INITIALIZE 


/[NO]CONFIRM 


The /NOCONFIRM qualifier specifies that P/OS should not 
verify that the volume is already in FILES-11 format. The 
/CONFIRM qualifier asks you to verify the initialization 
request if the volume is already in FILES-11 format. The 


/CONFIRM qualifier is the default. 


INSTALL 


3.33 INSTALL 


INSTALL includes a specific task in the System Task Directory, 
thus making it known to the system. 


An installed task is dormant until it is requested to run by the 


Executive. You can request an installed task to run through the 
RUN command or through a variety of Executive directives under 
program COnerol. Examples of such directives are: ROSTS 
(Request), RUNS (Run), and SPWNS (Spawn). See the P/OS System 
Reference Manual for details on the directives. 
Syntax 

INSTALL[/qualifier[{s]] [$S]filespec 


qualifier 
Can be one or more of the following: 


JEIX 

/NOREMOVE 
/READONLY_COMMON 
/TASK_NAME:taskname 
/{NO]WRITEBACK 


[S]filespec 


Specifies the name of the task image file containing the 
task you want to install. The default file type is .TSK. 
The dollar sign ($), if present, directs the system to 
search for the file in APPLSDIR. If you do not include the 
/TASK_NAME qualifier, the system installs the task under a 
mame based on the first six characters of the filename 
unless another name was assigned through the TASK= option of 
the Task Builder. 


Prompts 
File? filespec 

Qualifiers 

/FIX 
Loads and locks a task into memory after installing it. 
P/OS can service requests for a fixed task much more quickly 


because it is memory-resident and does not have to be loaded 
from disk. 


a9. 
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You can use the FIX command to fix a task that is already 
installed. See Section 3.28. 


/NOREMOVE 


When the DCL application exits, P/OS will not remove tasks 
Or regions that have been installed with the /NOREMOVE 
qualifier. 


/READONLY_COMMON 


Specifies that a common or region is to be installed as 
read-only. 


/TASK_NAME:taskname 


Specifies the name by which the task is to be referenced. 
The default is set at link time. This qualifier overrides 
the link-time specification. 


/{NO]WRITEBACK 


Applies only when you install a read-write common. This 
qualifier controls whether or not the system writes the 
common back to its task image either when you remove the 
common from memory or when the system checkpoints the 
common. 


If you use /WRITEBACK, then any changes made to the common 
while installed are copied to the common’s task image when 
the common is checkpointed or you remove it. 


If you specify /NOWRITEBACK, then changes made to the common 
are not copied back to the image. The default (that is, 1f 
you do not specify either), 1s /NOWRITEBACK. 
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3.34 LIBRARY 


LIBRARY creates and maintains user-written library files, or 


libraries. Libraries can contain macro definitions, object 
modules, or, in the case of universal libraries, anything. 
LIBRARY invokes’ the Librarian Utility program (LBR). (Refer to 
Chapter 7.) 

Syntax 


LIBRARY([/operation][/qualifier({s]] libr_spec input_file 
operation 


Represents a specific subcommand form of LIBRARY (refer to 
each separately listed LIBRARY command). 


qualifier 
Refer to each separately listed LIBRARY command. 
libr_spec 


Specifies the name of the library. The default type is 
.OLB, specifying an object module library. 


input_file 
Specifies input files used as input for a new library file 
created with the /CREATE qualifier. 

Prompts 


Operation? operation 
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3.35 LIBRARY/COMPRESS 


This command physically deletes modules that have been logically 
deleted through the LIBRARY/DELETE command. You can rename the 
resulting compressed library with this command. 
Syntax 
LIBRARY/COMPRESS[:(arg[,s])] libr_spec [new_libr_spec] 
arg 
Can be one or more of the following: 
GLOBAL: n 
MODULES:n 
BLOCKS =n 
libr_spec 
Is the name of the library to be compressed. 
new_libr_spec 
This optional parameter specifies a name for the newly 
compressed library. If you do not specify a name, the new, 


compressed file has the same name as the old one. The old 
File is not deleted after you create (compress) a new one. 


Prompts 
Library? libr_spec [new_libr_spec] 

Arguments 
If you are specifying more than one argument, the arguments 
must be enclosed in parentheses and separated by commas. If 
you are specifying only one argument, the parentheses are 


not necessary. 
GLOBALS:n 


The GLOBALS argument specifies the number of global symbols 
(entry point table entries) to allocate. The default nis 
the number of global symbols allocated in the old library. 
The maximum nis 4096. The value of n is always forced to 
zero for macro and universal libraries. 


LIBRARY/COMPRESS 


MODULES:n 


The MODULES argument specifies the number of entries to 
allocate in the module name table. The default value is the 
number of entries in the old library. The maximum number of 
module names is 4096. 


BLOCKS:n 


The BLOCKS argument specifies the size of the library in 
256-word blocks. The default size is the size of the old 
library. 


LIBRARY/CREATE 
3.36 LIBRARY/CREATE 


LIBRARY/CREATE creates a library. This command can optionally 
insert one or more modules into the newly created library. 


Syntax 


LIBRARY/CREATE[:(arg[,S])][/qualifier[s]] libr_spec 
[input_file[,s]] 


arg 
Can be one or more of the following: 
GLOBALS:n 
MODULES:n 
BLOCKS :n 
qualifier 
Can be one or more of the following: 
/{NO]GLOBALS 
/MACRO 
/OBJECT 
/ SQUEEZE 
/UNIVERSAL 


libr_spec 


Is the name of the library to be created. 


input_file 
Specifies the file or files to be used as input to the new 
library: tile. If no input files are specified, an empty 
library file is created. The default file types are .OBJ 
when creating object module libraries, .MAC when creating 


macro libraries, and .UNI when creating universal libraries. 
Prompts 


Library? 14 OP. 3S DEC 
Module(s)? input_file 
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Arguments 


If you are specifying more than one argument, the arguments 
must be enclosed in parentheses and separated by commas. If 
you are specifying only a single argument, the parentheses 
are not necessary. 


GLOBALS:n 


The GLOBALS argument specifies the number of global symbols 
(entry point table entries) to allocate. The default is 512 


for object libraries. The value n is always forced to 0 for 
macro and universal libraries; it can range from 0 through 
4096. 

MODULES:n 


The MODULES argument specifies the number of entries to 
allocate in the module name table. The default value is 
256. n can be from 0 through 4096. 

BEOCKo sn 


The BLOCKS argument specifies the size of the library in 
256-word blocks. The default size is 100 blocks. 


Qualifiers 
/{NO]GLOBALS 


/NOGLOBALS specifies that global symbols are not to _ be 
included in the entry point table. 


Use this qualifier if you want to use the same global 
symbols in more than one module. /GLOBALS is the default 
but 2S: a: No=Op; 
/ SQUEEZE 
The /SQUEEZE qualifier reduces the size of macro definitions 
by eliminating all trailing blanks and tabs, blank lines, 
and comments from macro text. You must specify an input 
file or files. 


This qualifier has meaning for macro libraries only. 


Macros that have been squeezed not only take up less room in 
the macro library file, but also take up less memory. 
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This /SQUEEZE qualifier is the equivalent of the LBR /SZ 
qualifier applied to the output library file when using the 
/CR qualifier. 

/MACRO 


The /MACRO qualifier specifies that the library being 
created is a macro library. 


/OBJECT 
The /OBJECT qualifier specifies that the Jlibrary being 
created is an object module library. This is the default 
and need not be specified. 


/UNIVERSAL 


The /UNIVERSAL qualifier specifies that the library being 
created is a universal library. 
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3.37 LIBRARY/DELETE 


LIBRARY/DELETE deletes modules from a library. (Refer to 
LIBRARY/REMOVE to remove global symbols (entry points) from a 
library.) 
Syntax 

LIBRARY/DELETE libr_spec module[,s] 


libr_spec 


Is the name of the library that contains modules’ for 
deletion. 


module 


Is the name of the module for deletion. (The LIBRARY/DELETE 
command will delete up to 15 modules.) 


Prompts 


Library? iibr_spec 
Module(s)? module 
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3.38 LIBRARY/EXTRACT 


LIBRARY/EXTRACT reads one or more modules from a library and 
writes them to a specified output file. This command can extract 
as many as eight modules with each execution. If you specify 
more than one module to be extracted, LIBRARY/EXTRACT 
concatenates those modules in the output file. 
Syntax 

LIBRARY/EXTRACT[/qualifier] libr_spec modules[,s] 
qualifier 

/OUTPUT[: filespec] 
libr_spec 

Is the name of the library for the extract (read) operation. 
module 

Specifies the modules that are to be extracted. If you do 

not include a list, all modules in the library are extracted 


and concatenated in the output file in alphabetical order. 
You can specify up to eight modules, separated by commas. 


Prompts 
Library? libr_spec 
Module(s)? module 
LO? Filespec 
Qualifier 


/OUTPUT[:filespec] 


The /OUTPUT qualifier specifies the file to which the 
extracted modules or macros are to be written. If you 
specify /OUTPUT without a filespec, the default is to write 
the modules to your terminal. This makes sense only for 
macro libraries or universal libraries containing text 
modules. 


Tf you do not include the qualifier, you will be prompted 


To?, to which you are to reply with a filespec. You can 
reply TI: to have the output printed on your terminal. 
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3.39 LIBRARY/INSERT 


This command inserts modules from one or more files into a 
Library. 


Syntax 
LIBRARY/INSERT([/qualifier[s]] libr_spec input_filespec[,s] 
qualifier 
Can be one or more of the following: 
/{NO]JGLOBALS 
/SELECTIVE_SEARCH 
/ SQUEEZE 
libr_spec 
Is the name of the library in which modules will be 
inserted. Any number of files can be specified and each 
file can contain any number of concatenated modules. 


input_filespec 


Is the name of the file that contains the module or modules 
for insertion. 


Prompts 
Library? Libr. spec 
Module(s)? module 
Qualifiers 
/{NO]GLOBALS 


/NOGLOBALS specifies that entry points for the specified 
modules are not to be included in the entry point table. 


Use this qualifier if you want to insert global symbols 

having the same name as symbols already in the library file. 

The default, /GLOBALS, does not permit this operation. 
/SELECTIVE SEARCH 

Sets the selective search attribute bit in the module header 


of object modules as they are inserted into an object 
library. You must specify an input file or files. 
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Object modules with this attribute are given special 
treatment by the Task Builder. Global symbols defined in 
modules with the selective search attribute are not included 
alg 9 the Task Builder’s symbol table unless they were 
previously referenced by other modules. 


/ SQUEEZE 
Reduces the size of macro definitions by eliminating all 
trailing blanks and tabs, blank lines, and comments from 


macro text. You must specify an input file or files. 


Macros that have been squeezed not only take up less room in 
the macro library file, but also take up less memory. 


This qualifier is the equivalent of the LBR /SZ qualifier 
applied to the output file. 
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3.40 LIBRARY/LIST 


This command lists the name of all modules which reside in a 
library. LIBRARY/LIST either displays these names on = your 
terminal or writes them in an output file, depending on whether 
you supply a filespec or not. 
Syntax 
LIBRARY/LIST [:filespec][/qualifier] libr_spec 
qualifier 
Can be one or more of the following: 
/BRIEF 
JEL 
/[NO]NAMES 
Filespec 
Is the name of the optional output file. If you ‘ado not 
include a filespec as an argument to /LIST, the library is 
listed on your terminal. 


libr_spec 


Is the name of the library that contains the modules to _ be 
listed. 


Prompts 

Library? libr_spec 
Qualifiers 
/BRIEF 


The /BRIEF qualifier specifies that you want the list to 
include only the module names. This is the default. 


JRUUL 
The /FULL qualifier requests a listing of all module names, 


along with a module description including size, date of 
insertion, and module-dependent information. 
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/{NO]NAMES 
The /NAMES qualifier requests a list of modules in the 


library, along with their entry points. The default is 
/NONAMES. 
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3.41 LIBRARY/REMOVE 


This command removes global symbols (entry points) from a 
library. (Refer to LIBRARY/DELETE to delete object modules from 
a library.) 

Syntax 


LIBRARY/REMOVE libr_spec global[,global[,s]] 


libr_spec 
Is the name of the library that contains global symbols to 
be deleted. 

global 
Is the name of a global symbol for deletion. You can 


specify as many as 15 global symbols. 
Prompts 


Library? libr_spec 
Symbol? globals 
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3.42 LIBRARY/REPLACE 


This command replaces a module ina library with a new module of 
the same name and deletes the old module. When a match occurs on 
a module name, the existing module is logically deleted and all 
its entries are removed from the global symbol table. 
Syntax 

LIBRARY/REPLACE[/qualifier[s]] libr_spec filespec[,s] 
qualifier 

Can be one or more of the following: 

/{[NO]GLOBALS 

/SELECTIVE_SEARCH 

/ SQUEEZE 


libr_spec 


Is the name of the library that contains the module _ for 
replacement. 


filespec 
Is the name of the file or files that contain the new 


modules. If the module to be replaced does not exist in the 
library, LIBRARY performs an insert operation. 


Prompts 
Library? libr_ spec 
Module(s)? module 


Qualifiers 

/{NO]GLOBALS 
/NOGLOBALS specifies that entry points for the specified 
modules are not to be included in the entry point table. 
The default is /GLOBALS. 

f/SEBLECTIVE SEARCH 
Sets the selective search attribute bit in the module header 


of object modules as they are inserted into an object 
library. 
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Object modules with the selective search attribute are given 
Special treatment by the Task Builder. Global symbols 
defined in modules with the selective search attribute are 
only included in the Task Builder’s symbol table if they 
were previously referenced by other modules. 


/ SQUEEZE 
Reduces the size of macro definitions by eliminating all 
trailing blanks and tabs, blank lines, and comments from 
macro text. 
Macros that have been squeezed not only take up less room in 
the macro library file, but also take up less memory in the 


assembler when they are invoked. 


This is the equivalent of the LBR /SZ qualifier applied to 
the input file. 
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3.43 LINK 


LINK invokes the Professional Application Builder (PAB), which 
links object modules and routines from user and system libraries 
to form an executable task. 

Syntax 


LINK[/qualifier[s]] 
filespec[/file-qualifier[s]]{,filespec[,s]] 


qualifier 
Can be one or more of the following: 


/ANCILLARY_PROCESSOR[:n] 
/{NO]CHECKPOINT: arg 


SYSTEM 
TASK 
fCODE: Carg(5s:)) 
EAE 
FPP 
PIC 
POSITION INDEPENDENT 
/COMPATIBLE 


/{NO]CROSS_REFERENCE 
/(NO]DEBUG[:filespec] 
/ERROR_LIMIT:n 
/[NO]EXECUTABLE[:filespec] 
/FAST_MAP 
/FULL_SEARCH 
/{NO]HEADER 
/{NO]IO_PAGE 
/LONG 
/MAP[:options-spec] 
/{NO]MEMORY_MANAGEMENT[ :n] 
/OPTIONS[ :options-spec] 
/{NO]PRIVILEGED[:n] 
/[NO]RECEIVE 
/[NO]RESIDENT_OVERLAYS 
/SAVE 
/({NO]SEGREGATE 
/ SEQUENTIAL 
/SHAREABLE[: arg] 
COMMON 
LIBRARY 
TASK 
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/SLAVE 
/SYMBOL_TABLE[:filespec] 
/(NO]SYSTEM_LIBRARY DISPLAY 
/(NO]TASK[:filespec] 

/TKB 

/ TRACE 

/[NO]WARNINGS 

/WIDE 


fFilespec 


Is the name of the file containing the object module. 
file-qualifier 


/{NO]CONCATENATE 
/DEFAULT_ LIBRARY 
/{NO]GLOBALS 
/LIBRARY 


/SELECTIVE_SEARCH 
/OVERLAY_DESCRIPTION 


Prompts 

File(s)? filespec[,s] 
Qualifiers 
/ANCILLARY_PROCESSOR[:n] 


Identifies the task as an Ancillary Control Processor (ACP). 
The parameter n specifies the base relocation register. 
Acceptable values are 0, 4, or 5. The default is 5. 


In TKB format, apply the /AC qualifier to the .TSK filespec. 


/(|NO]CHECKPOINT: arg 
SYSTEM 
TASK 


specifies that the task is to be (or is not to be) 
checkpointable. Checkpointability of tasks 1s an important 
part of the operating system’s ability to share resources. 
When a higher priority task seeks access to system memory, a 
checkpointable task of lower priority is checkpointed, or 
rolled out to the disk to be stored in its current state 
until the higher priority task exits, whereupon the lower 
priority task returns and takes up where it left off. 
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If you do not use the /CHECKPOINT qualifier, your task is 


built noncheckpointable. The default is /NOCHECKPOINT. A 
noncheckpointable task cannot be dislodged by a task of 
higher priority. Therefore, you should always build your 


tasks checkpointable unless you have some important reason 
for not doing so. 


You can specify how the checkpointing of the task is handled 
through the arguments to the /CHECKPOINT qualifier. Your 
task can be checkpointable to the system checkpoint file 


with the SYSTEM Option. This is the default. 
LINK/CHECKPOINT and LINK/CHECKPOINT:SYSTEM are equivalent 
commands. 


Tasks built with system checkpointing cannot be checkpointed 
if the system checkpoint file is full. 


You can also reserve checkpoint space for the task as part 
of its own task image file by using LINK/CHECKPOINT:TASK. 


Such tasks are always checkpointable. (If there is no 
system checkpoint file, you can only run one copy of such 
tasks.) 


It should be apparent that the checkpointability of a task 
has an impact on the efficient operation of the entire 
system as well as on the task itself. If the task is built 


noncheckpointable, it can block more important tasks from 
running. If it is built with task checkpointability, 
mass-storage space is reserved that may never be used. If 


it is built with system checkpointability, there may be no 
room for it in the system checkpoint file. 


In TKB format, for -/CHECKPOINT:SYSTEM; -appiy the /CP 
qualifier to the task image file. For /CHECKPOINT:TASK, 


apply the /AL qualifier to the task image file. For 
/NOCHECKPOINT, apply the /-CP qualifier to the task image 
file. 


/CODE:(arg[,s]) 
EAE 
FPP 
PIC 
POSITION INDEPENDENT 


The /CODE qualifier specifies that the code for the task 
relies on certain hardware elements or employs certain 
techniques. See the RSX-11M/M-PLUS and Micro/RSX Task 
Builder Manual for more information. 
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The EAE argument specifies that the task uses the Extended 
Arithmetic Element. In TKB format, apply the /EA qualifier 
to the .TSK filespec. 


The FPP argument specifies that the task uses the Floating 
Point Processor. This hardware is optional and may not be 
part of your system. In TKB format, apply the /FP qualifier 
to the .TSK filespec. 


The PIC and POSITION_INDEPENDENT arguments are identical and 
specify that the resident common or library being built is 
position-independent. In TKB format, apply the yet 
qualifier to the .TSK or .STB filespec. 


If you want to use more than one argument, enclose them in 
parentheses, separated by commas. 


/COMPATIBLE 


Specifies that the task be built in compatibility mode. 
This means that memory-resident overlay segments are aligned 
on 256-word boundaries’ for compatibility with otner 
implementations of the mapping directives. Without this 
qualifier, overlay segments are aligned on 32-word 
boundaries. 


in: TKB format; apply the .sCM qualifier to: the «TSK fitespec. 
/[NO]CROSS_REFERENCE 


Specifies that a listing of symbol cross-references is to be 
appended to the Task Builder map file. 


If you include this qualifier, you automatically include the 
/MAP qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. Tf you 
supply a name, the map file appears in your current 
directory. 


In TKB format, apply the /CR qualifier to the .MAP filespec. 
/{NO]DEBUG[:filespec] 


Specifies the inclusion of a debugging aid in the _ task 
image. A debugging aid permits you to interrupt the running 
of a task and inspect registers and other memory locations 
at ‘various. Stages. -1f you give no: filespec, the defauit:.1s 
LBO:[1,5]ODT.OBJ, which is ODT, the On-line Debugging Tool, 
a DIGITAL=supplied Utility, “ODT is incorporated in the task 
you are building. ODT can be used only on tasks written in 
the MACRO-11 Assembly Language. 
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See the IAS/RSX-11 ODT Reference Manual EOr further 
information. 


If you have a user-written debugger, name the file it is in 
when you use this qualifier. This file should be an object 
module. 


In TKB format, apply the /DA qualifier to the .TSK filespec 
if you want to use ODT. If you want to use a user-written 
debugger, apply the /DA qualifier to the input filespec 
naming the debugger. 


/ERROR_LIMIT:n 


Directs the Task Builder to abort LINK after n diagnostics 
errors have been produced. 


In TKB format, apply the /XT:n qualifier to the .TSK 
filespec. 


/(NO]EXECUTABLE[:filespec] 
see /[NO|TASK. 
/FAST_MAP 


Use this qualifier if you want P/OS to interpret I0OT 
instructions in your task as requests to perform fast remap 
operations. When you use the /FAST_MAP qualifier to Ilink 
your task, P/OS -interprets. all. JOT instructions as fast 
remap requests. See the P/OS System Reference Manual for 
details on fast remap operations. 


In TKB format, apply the /FM qualifier to the .TSK filespec. 


/FULL_SEARCH 


Specifies that when processing modules from the default 
object module library, the Task Builder should search all 
co-tree overlay segments for matching definitions or 
references. 


Without this qualifier, unintended global references between 
co-tree overlay segments are eliminated. Definitions of 
global symbols from the default library are restricted in 
scope to references in the main root and the current tree. 


In TKB format, apply the /FU qualifier to the .TSK filespec. 
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/ LONG 


Specifies that the map file produced by the Task Builder 
include additional file information on modules used in the 
task build. The long map does not include file information 
on modules from the system library. 


If you include this qualifier, you automatically include the 
/MAP qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. Lr Vou 


supply a name, the map file appears in your current 
directory. 


In TKB format, apply the /-SH qualifier to the .MAP 
filespec. 


/MAP([:options-spec] 


Specifies that you want to produce a memory allocation, or 
map file. If you use /MAP as a command qualifier, without a 
options-spec argument, the map appears in your directory; 
its filename is derived from the name of the first input 
File named in the command line. Its file type is .MAP. 


If you use /MAP with a options-spec argument, either as a 
command qualifier or a filespec qualifier, the map appears 
in your directory with a filename you have given. 


The following qualifiers automatically direct the Task 
Builder to produce a map with special characteristics: 


/CROSS_REFERENCE 

/ LONG 

/SYSTEM_ LIBRARY DISPLAY 
/WIDE 


You do not need the /MAP qualifier with these qualifiers 
unless you want to add a filespec argument to /MAP. These 
other map-related qualifiers can be used as either command 
OP filespec qualifiers, but they have no affect on 
filenames. 


In TKB format, the /MAP qualifier corresponds to the second 


position in the list of TKB output files and has the default 
file type .MAP. 
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/{NO]HEADER 


/NOHEADER sets the Task Builder STACK option to 0. If you 
are building a shared region or a driver, you should specify 
this qualifier. If you specify this qualifier, you cannot 
use the STACK option. The default is /HEADER. 


In TKB format, apply the /-HD qualifier to either the .TSK 
or .STB filespec and specify the STACK=0 option. See 
/SHAREABLE. 


/{NO]IO_PAGE 


/NOIO_PAGE indicates to the Task Builder that the task is 
over 12K and purposely does not map to the I/O page. This 
qualifier is for building privileged tasks. only. The 
default is /IO_PAGE. 


/{NO]MEMORY_MANAGEMENT[ :n] 


Specifies that the task is being built for a system with (or 
without) memory management hardware. Use the /NOMEMORY_ 
MANAGEMENT qualifier when you are building a task on a 
system with memory management to be run on an RSX-11M (or 


RSX-11S) system without the memory management hardware. The 
value n specifies the highest physical address of a task on 
the target system; it can be 28 (the default) or 30. The 


default is /MEMORY_MANAGEMENT. 


In TKB format, apply the /-MM qualifier to the .TSK 
filespec. 


/SHAREABLE[: arg] 
COMMON 
LIBRARY 
TASK 


/SHAREABLE:TASK is the default value and identifies the task 
as a multiuser task. Such tasks permit more than one user 
to share the read-only partition of a single task. When you 
specify /SHAREABLE:TASK, the Task Builder divides the task 
into two regions: region 0 contains the read-write portion 
of the task and region 1 contains the read-only portion of 
the task. When multiuser tasks are installed, multiple 
requests for the task to run cause the system to duplicate 
only the read-write portion of the task for each request 
after the first. The ROPAR option permits you to name the 
portion in which region 1 is to reside. In TKB format, 
apply the /MU qualifier to the .TSK filespec. 
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/SHAREABLE:COMMON informs the Task Builder that a shareable 
common 1s being built. You should always use the /NOHEADER 
qualifier with /SHAREABLE:COMMON. If you do not’ specify 
CODES PIC or CODE: POSITION _INDEPENDENT, TKB builds = an 
absolute shared common. All program sections in the common 
are marked absolute. alga you Specify -CODEPIC. or 
CODE: POSITION_INDEPENDENT, all program sections in the 
common are marked relocatable. In either case, the .STB 
file contains all the program section names, attributes, 
lengths, and symbols. The .STB file of a common built 
/SHAREABLE contains all defined program sections. In TKB 
format, apply the /CO qualifier to the .TSK or .STB 
filespec. /SHAREABLE:TASK defaults to /SEGREGATE. 


/SHAREABLE: LIBRARY informs the Task Builder that a shareable 
library is being built. You should always use /NOHEADER 
with /SHAREABLE: LIBRARY. TKB includes only one program 
section in the .STB file. If you do not specify CODE:PIC or 
CODE: POSITION_INDEPENDENT, TKB names the program section 
-ABS, makes the library position-dependent, and defines all 


symbols as absolute. LE you specify CODE PIC or 
CODE: POSITION_INDEPENDENT, TKB gives the program section the 
Same name as the root segment of the library. TKE. Lorces 


this name to be the first and only declared program section 
in the library. TKB declares all global symbols in the .STB 
file relative to that program section. In TKB format, apply 
the /LI qualifier to the .TSK or «STB filespec. 


/OPTIONS[ :options-spec] 


Specifies one or more Task Builder options. Use this 
qualifier if you need to use any of the Task Builder 
options. For -tull. aAmtormation, “en options, see the 


RSX-11M/M-PLUS and Micro/RSX Task Builder Manual. 


You can supply options for this qualifier in two ways: 
Supply the filespec of a file containing the options, or 
specify the options themselves. If you do not include a 
filespec with this qualifier, you are prompted for options. 
If you want to enter multiple options, you use a comma after 
each option listed. To list multiple options on individual 
lines, end each line with a comma. 


If you include a filespec with this qualifier, this file 
should contain only the option names, comments, and the 
arguments associated with the options, as shown: 


UNITS=8 

ASG=TTO< 728 

> COMMENTS, PRECEDED BY SEMICOLON, ALLOWED 
PAR=KROBAR: 50000:40000 
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This file should only the option statements and comments 
preceded by the semicolon (;). Comments preceded by the 
exclamation point (!) are not accepted in this instance. Do 
not put any slashes in the file. 


Note that the ABORT option is the only means of preventing a 
task build once you have begun issuing commands to the Task 
Builder. A CTRL/Z simply directs the Task Builder to begin 
the task build based on whatever instructions you have 
issued up to that point. Thus, if you want to be sure of 
being able to stop a task build in this way, you must 
include the /OPTIONS qualifier in the LINK command line. 
This assures the availability of the ABORT option. If you 
are typing the command line and make a mistake, specify the 
/OPTIONS qualifier, press RETURN, and enter the ABORT=0 
option. Then press RETURN and the task build aborts. 


/PRIVILEGED[:n] 


Indicates that task is privileged. The argument n specifies 
the base relocation register. Acceptable values are QO, 4, 
OF-3e Whe sdetawlt..1s "5 


In, TRE format, apply the .,PR qualitier co: the <TSk. 21 lespec:. 


/[NO]RECEIVE 


Indicates that the task may (or may not) receive messages by 
means of the Executive directive SEND. /RECEIVE is the 
default. 


In TKB format, apply the /SE qualifier to the .TSK filespec. 
/({NO]RESIDENT_OVERLAY 


Enables (or disables) recognition of the memory-resident 
overlay operator (!) in an overlay description file. The 
qualifier is used with the /OVERLAY_DESCRIPTION qualifier 
when the task has memory-resident overlays. The default is 
/RESIDENT_ OVERLAY. 


In TKB format, apply the /RO qualifier to the .TSK filespec. 


/SAVE 


The /SAVE qualifier specifies that you want to retain the 
indirect command file created by DCL to pass your LINK 
command to TKB. If you include /SAVE in your LINK command 
line, a file named ATLNK.TMP appears in your directory after 
the task build completes. Since this file always has the 
same name, you should give it a name related to the task it 
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builds, such as SHEMPBLD.CMD. Then you can issue a command 
in the following form and duplicate the task build that 
originally produced the command file: 


>LINK @SHEMPBLD 


This file is also useful for comparing LINK command syntax 
with TKB syntax because it includes the full translation of 
the LINK command into TKB format. 


/{[NO]SEGREGATE 


/SEGREGATE causes the Task Builder to order program sections 
alphabetically by name within access code (RO followed by 
RW). If you also specify /SEQUENTIAL, TKB orders’ program 
sections in their input order by access code. 


/NOSEGREGATE is the default. TKB interleaves RO and RW 
program sections. When combined with /SEQUENTIAL, 
/NOSEGREGATE results in a task with program sections 
allocated in input order with its RW and RO sections 
interleaved. If you use /NOSEQUENTIAL and /NOSEGREGATE 
together, which is the default for both, TKB orders program 
sections alphabetically with RW and RO sections interleaved. 


In TKB format, use the /[{-]SG qualifier on the .TSK 
filespec. 


/SHAREABLE:TASK defaults to /SEGREGATE. 
/SEQUENTIAL 


Directs Task Builder to construct a task image from program 
sections in the order in which they appear. Normally, the 
Task Builder finds all program sections referenced in all 
modules in an overlay segment and then builds the task with 
those program sections in alphabetical order. Do not use 
this qualifier to build tasks that rely on alphabetical 
allocation of program sections, such as FORTRAN I/O handling 
modules and FCS modules from SYSLIB. See also /SEGREGATE. 


In TKB format, apply the /SQ qualifier to the .TSK filespec. 
/ SLAVE 

Specifies that the task is to be slaved to a sending task. 

When a slaved task successfully executes the Executive 

directive Receive Data, it is given the [UIC] and TTI: Of 


the sending task. This qualifier applies only to systems 
with multiuser protection. 
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Slaved tasks cannot be run with a RUN command. They must be 
run by the sending task. 


In TKB format, apply the /SL qualifier to the .TSK filespec. 
/SYMBOL_TABLE[:filespec] 


Directs that a symbol table file be produced. The default 
name is that of the first input file and the default type is 
.STB. The options-spec parameter overrides the defaults. 
This qualifier is used when building shared regions. 


In TKB format, this qualifier corresponds to the third 
position in the list of TKB output files, called the .STB 
Filespec. 


/{NO]SYSTEM_ LIBRARY DISPLAY 


Directs the Task Builder to produce a map that includes (or 
does not include) global symbols defined or referenced by 
the task. These symbols are found in LBO:({1,5]SYSLIB or in 
any shared regions linked to using TKB options. This map is 
usually considerably longer than the default map. The 
information displayed illuminates the contribution that 
SYSLIB or the shared regions make to the task. 


If you include this qualifier, you include the /MAP 
qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. 


If you supply a name, the map file appears in your current 
GErEeCEOrY:. See the RSX-11M/M-PLUS and Micro/RSX Task 
Builder Manual for more information. 


In TKB format, apply the /MA qualifier to the .MAP filespec. 


/TASK[:taskspec] 
/EXECUTABLE[:taskspec] 


Specifies a name for the task image file different from that 
of the first input file plus the type .TSK. If used as a 
options-spec qualifier, the task name is derived from _ the 
mame of the file to which the qualifier is attached. 
/EXECUTABLE iS a synonym. 


In TKB format, this qualifier corresponds to the first 
position in the list of TKB output files, called the .TSK 
filespec. 
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/NOTASK 
/NOEXECUTABLE 


Specifies that LINK produce no task image file. This 
qualifier is useful when you want to use some facility of 
the Task Builder without building a task, to check for 
unresolved symbol references or make a map, for instance. 
/NOEXECUTABLE 1S a synonym. 


In TKB format, leave the first position in the list of MTKB 
output filespecs blank, followed by a comma (,). 


/TKB 
Specifies that the default Task Builder be used to build the 
task. This is the default; the qualifier is included for 
completeness. 
You can also invoke the default Task Builder from DCL with 
the command RUN SPAB. You must follow TKB format if you run 
the default Task Builder in this fashion. See the 
RSX-11M/M-PLUS and Micro/RSX Task Builder Manual fora 
description of the TKB command format. 

/ TRACE 


Specifies that the task is to be traceable. When you use 
this qualifier, a trace trap occurs on the completion of 
each instruction when the task 1s run. 


In TKB format, apply the /TR qualifier to the .TSK filespec. 


/{NO]WARNINGS 


/NOWARNINGS suppresses diagnostic messages issued by the the 
Task Builder. Two messages are suppressed: 


n undefined symbols segment "segname" 

and 

Module "modulename" multiply defines P-section "psectname" 
The default is /WARNINGS. 


In TKB format, use the /[-]NM qualifier on the  .TSK 
filespec. 
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/(|NO]WIDE 


Specifies that the Task Builder map be printed in 132-column 
format. The default is /NOWIDE. 


If you include this qualifier, you include the /MAP 


qualifier as well. You do not need the /MAP qualifier 
unless you want to supply a name for the map file. If you 
supply a name, the map file appears in your. current 


directory. 
In TKB format, apply the /WI qualifier to the .MAP filespec. 
Parameter Qualifiers 


Any input file can have a parameter qualifier applied to it, 
identifying the kind of file that it is. 


/{NO]CONCATENATE 


Identifies the input file as a concatenated object file; 
this is the default. All modules in the file are processed 
to form the task image. /NOCONCATENATE specifies that only 
the first object module encountered is to be processed, 
regardless of how many are present. 


In TKB format, apply the /CC qualifier to an input file 
containing concatenated object modules. 


/LIBRARY 
Identifies the file as an object module library. This 
qualifier is required for any input library file and is 
prohibited: for any: Gtiner type Of Tie. The default file 


type: for object libraries: 2s .OLB: 


The Task Builder searches the library file to resolve all 
undefined global symbol references from files appearing to 
the left of the library file in the LINK command line. The 
Task Builder then extracts any and all modules that resolve 
undefined references and includes them in the task image. 
See also /INCLUDE. 


/ INCLUDE: modulei[:...modulen] 


You can specify as many as eight module names from a library 
using /INCLUDE. You must specify at least one. If you uSe 
the optional module arguments, the Task Builder takes only 
those modules from the library. The module names are 
defined at assembly time. 
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If you want both to resolve undefined references to global 


symbols and to specify modules, you must use this qualifier 
twice. 


In TKB format, apply the /LB qualifier to an input library 
file for both /LIBRARY and /INCLUDE. 


/DEFAULT_LIBRARY 


Specifies that the file to which it is appended replace the 
system object module library, LBO:[{1,5]SYSLIB.OLB, as the 
default library that is searched (in order to. resolve 
unresolved global references). This qualifier can be 
applied to only one file; that file must be an object module 
library having the file type .OLB. 


In TKB format, apply the /DL qualifier to an input library 
file. 


/{NO]GLOBALS 
Specifies that global symbols referenced and defined by the 
input file are (or are not) to be included in the map output 


File. The default is /GLOBALS. 


In TKB format, apply the /-MA qualifier to the input file. 


/SELECTIVE_SEARCH 


Instructs the Task Builder to search the file only for 


undefined references to global symbols. This qualifier is 
most useful when building an Ancillary Control Processor or 
other privileged task that maps into the Executive. If you 


do not specify this qualifier, all of the Executive’s global 
symbol definitions are included in the task build, whether 
or not the file contains undefined references to the global 
symbol. The Executive contains a myriad of modules. In 
these and similar circumstances, this qualifier considerably 
shortens the symbol table search and improves system 
performance. 


If you do not use this qualifier, all global symbols from 
the input file are included in the task image. 


In TKB format, apply the /-SS qualifier to an input file. 
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/OVERLAY DESCRIPTION 


Specifies that the input file is an overlay description file 
(type .ODL) that controls the linking of the task. No other 
input file can be specified if you use this qualifier. The 
200% file Specifies input files to LINK. 
/OVERLAY_DESCRIPTION can be either a command qualifier or a 
Filespec qualifier. 


In TKB format, use the .ODL file as the only input file to 


the right of the equal sign (=) with the /MP qualifier 
applied to the .ODL filespec. 
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3.44 LINK/C81 


This section explains how you can link COBOL-81 object files to 
produce a task image (.TSK file). 


Syntax 
LINK/C81[/qualifier[s]] filespec[,s] 
LINK/COBOL[/qualifier[s]] filespec[,s] 
qualifier[s] 


Although the format shows them as command qualifiers, you can 
append the following qualifiers to either the command or a file 
specification. When you use the LINK/C81 command, the _ two 
locations are equivalent. 


/{NO]EMS 

/FMS :NORESIDENT 
/OTS:[NO]RESIDENT 
/{NO]RMS:[NO]RESIDENT 
/{NO]MAP 

/{NO]DEBUG 


fFilespec[,s] 


Specifies the file or files to be linked. The default file 
type is .SKL. 


The LINK/C81 command links object modules indirectly through 
their associated .SKL files. Therefore, if you include file 
types in any file specifications, you must use .SKL rather 
than .OBJ. Each .SKL file corresponds to an object module 
(.OBJ file) that is included in the task image. Except for 
the file type, the .SKL file and object module have 
identical file specifications. 


You can list any number of .SKL files as input files in any 
order, separated by commas. 


Prompts 


File(s)? filespec[,s] 
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Qualifiers 
/OTS:[NO]RESIDENT 


The /OTS:RESIDENT qualifier includes memory-resident OTS in 
your task image. When you specify /RMS:RESIDENT as well as 
/OTS:RESIDENT, LINK/C81 clusters these two libraries by 
default. If you can take advantage of the clustering 
feature, the resulting task image is smaller and program 
execution speed is improved. You should use /OTS:RESIDENT, 
because the Professional 300 Series only Supports 
memory-resident OTS and RMS. 


The /OTS:NORESIDENT qualifier includes the disk-resident OTS 
library in your task image. 


The default is /OTS:NORESIDENT. 
/{NO]RMS:[NO]RESIDENT 


The /RMS:RESIDENT qualifier creates a reference to the 
Shared RMS-11 memory-resident library, RMSRES. This library 
includes input/output support for sequential, indexed, and 
relative file organizations. 


When you specify /OTS:RESIDENT as well as /RMS:RESIDENT, 
LINK/C81 clusters these two libraries by default. If you 
can take advantage of the clustering feature, the resulting 
task image is smaller and program execution speed is 
improved. 


The /NORMS qualifier is equivalent to /RMS:NORESIDENT. 


/{NO]MAP 


The /MAP qualifier causes LINK/C81 to produce a Task Builder 
map file with the file type .MAP. The /NOMAP qualifier 
tells LINK/C81 not to produce a memory map file. 


The default is /NOMAP. 

/{NO]DEBUG 
The /DEBUG qualifier tells LINK/C81 to include the COBOL-81 
SYMBOLIC Debugger in your task image. To use this 
qualifier, you must also use the /DEBUG qualifier to the 


COBOL command. The /NODEBUG qualifier tells LINK/C81 not to 
include the COBOL-81 Symbolic Debugger in your task image. 
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The default is /NODEBUG. 


/({NOJ]FMS 
/FMS:NORESIDENT 


The /FMS qualifier causes LINK/C81 to include Forms 
Management Services (FMS) Jlibrary support in your task 
image. You must use this qualifier if you call FMS routines 
from your program. 


The /NOFMS qualifier tells LINK/C81 not to include FMS 
SUpDOrT. 


The default is /NOFMS. 


The /FMS:NORESIDENT qualifier causes LINK/C81 to include 
Support for a non-memory-resident FMS library in your task 
image. Since no resident FMS libraries are supported under 
P/OS, this qualifier is equivalent to /FMS. 


For more detailed information about how to create ae task 


image uSing LINK/C81, refer to the COBOL-81 RSX-11M/M-PLUS 
User’s Guide. 
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3.45 LOAD 


The LOAD command loads a device driver in the P/OS Operating 


System. Both the driver task image and symbol table file must 
reside in LB:[ZZSYS]. The filenames must be xxDRV.TSK and 
xxDRV.STB respectively, where "xx" is the logical device name 
mnemonic. 

Syntax 


LOAD device_mnemonic 
filespec 


Is the logical device name associated with the device 
driver. 


Prompts 


Device mnemonic? device mnemonic 
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3.46 MACRO 


MACRO invokes the Professional MACRO-11 Assembler (PMA) to 
assemble one or more MACRO-11 assembly language programs into a 
Single relocatable object module suitable for processing by the 
Professional Application Builder (PAB). 


Syntax 


MACRO[/command-qual[s]] 
filespec[/file-qual[({s]][,filespec[,s]] 


command-qual 


Can be one or more of the following: 


/{NO]CROSS_REFERENCE 
/DISABLE:(arg[,Ss]) 

ABSOLUTE 

BINARY 

CARD FORMAT 

GLOBAL 

LOCAL 

LOWERCASE 

REGISTER DEFINITIONS 

TRUNCATION 
/ENABLE: (arg[,$]) 

ABSOLUTE 

BINARY 

CARD_FORMAT 

GLOBAL 

LOCAL 

LOWERCASE 

REGISTER_DEFINITIONS 

TRUNCATION 
/({NO]|LIST[:filespec] 
/{NOJOBJECT[:filespec] 
/{NO]SHOW[:(arg[,S8])] 

ALL 

BINARY 

CALLS 

COMMENTS 

CONDITIONALS 

CONTENTS 

COUNTER 

DEFINITIONS 

EXPANSIONS 

EXTENSIONS 

LISTING DIRECTIVES 

OBJECT BINARY 

SEQUENCE_NUMBERS 
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SOURCE 
SYMBOLS 
/([NO]WIDE 
filespec 


Specifies one or more input files’ for the MACRO-11 


Assembler. These input files must contain MACRO-11 source 
code. Multiple filespecs must be separated by commas. 
Filespecs must include a filename. If no file type is 
given, the default file type (.MAC) is applied. If the 


parameter qualifier /LIBRARY is used, .MLB is the default 
file type. No wildcards are accepted by MACRO. 


fFile-qual 
Can be one or more of the following: 


/LIBRARY 
JPRoo th 


Prompts 
File(s)? filespec[{,s|] 

Command Qualifiers 

/([NO]LIST{:filespec] 
Specifies whether an assembly listing should be generated. 
The default is /NOLIST, meaning no assembly listing is 


generated. 


Lf “you. do Mob, ‘Supply a@ ‘Elle specification, for this 


qualifier, the listing has a filename derived from the name 
of the last source file in the MACRO command, with the file 
type. «LST, If you want the listing to have a different 


name, supply the name as an argument to the /LIST qualifier. 
The listing file appears in your default directory. 


If your command line includes the /CROSS_REFERENCE 
qualifier, /LIST is implied and need not be specified. 


LE your command dine: includes: jisting=control. arguments to 
either /SHOW or /NOSHOW, /LIST is implied and need not be 
specified. 


The only time you need to use /LIST with /CROSS_REFERENCE or 


/{[NO]SHOW is when you want to give the listing file a 
Filespec other than the default. 
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/(NOJOBJECT[:filespec] 


Specifies whether an object module should be generated. The 
default is /OBJECT, meaning an object module is generated. 
If you do not supply a file specification, the object file 
has a name derived from the name of the last source file and 
the file type .OBJ. If you want the object file to have a 
different name, give the name as an argument to the /OBJECT 
qualifier. 


You can name the object file after any of the source files 
listed in the MACRO command by using /OBJECT as a filespec 
qualifier. If used as a filespec qualifier, /OBJECT cannot 
take a filespec argument. 


The qualifier /NOOBJECT specifies that no object module is 
generated. You can use this qualifier if you want to use 
other facilities of the assembler, to get an assembly 
listing, for instance, without creating an object module. 


/[NO]CROSS_REFERENCE 


Specifies whether a cross-reference listing should be 
generated and appended to the assembly listing. The default 
is /NOCROSS_REFERENCE. 


The cross-reference listing locates all user-defined and 
MACRO symbols that appear in the source program. 


When you specify this qualifier, you are also specifying the 
UIST qualifier by ilplaeation:. An assembly listing is 
generated in your directory. If you want to change the name 
of the disting file, yous must “use- /LIST “with -a@ file 
Speciircation in. addition to -/CROSS. REFERENCE. 


/BNABLE: (arg[,s& 


7S] ) 
/DISABLE:(arg[, 


S]) 
These qualifiers override the .ENABL and .DSABL assembler 
directives included in the source program being assembled. 
The .ENABL and .DSABL directives invoke or inhibit various 
aspects of the assembly. Table 3-2 summarizes the arguments 
to /ENABLE- and /DISABLE and gives their MACRO-11 
equivalents. There is a default setting for each of these 
directives, even if you do not specify them in your code or 
command line. 


These qualifiers affect the entire assembly. Loe. “poe 
example, your MACRO command includes the qualifier 
/ENABLE:LOWER_CASE, the assembler does not convert any 
lowercase source text to uppercase, regardless of any .DSABL 
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LC or .ENABL LC directives in the source code. The same 
goes for /DISABLE:LOWER_ CASE. All - ENABL or .DISABL LC 
directives are ignored. 


If you specify only one argument to /ENABLE or /DISABLE, you 
need not include the parentheses, but if you have more than 
one argument, they must be separated by commas and enclosed 
in parentheses. 


Table 3-2: The Enable and Disable Qualifiers 


Function MACRO Description 


Syntax 


Assembly Functions Disabled by 


ABSOLUTE 


BINARY 


CARD FORMAT 


LOCAL 


LOWERCASE 


AMA 


ABS 


CDR 


LSB 


sc 


Default 


Enabling this function causes 
relative mode addresses (mode 67) 
to be assembled as absolute 
addresses (mode 37). 


Enabling this function produces 
absolute binary output in FILES-11 
format. 


Enabling this function causes 
source columns 73 and greater to 
be treated as a comment. 


Enabling this: Eunction: permits: the 
disabling or enabling of a local 
symbol block. 


Enabling. this. function Causes 
MACRO-11 to accept lowercase ASCII 
input. The default is to convert 
it to uppercase. 
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Function MACRO Description 
Syntax 
TRUNCATION FPT Enabling this function causes 


floating-point truncation. The 
default is floating-point 
rounding. 


Assembly Functions Enabled by Default 


REGISTER_ REG Disabling this function. inhibits 

DEFINITIONS the normal MACRO-11 default 
register definitions. The default 
1s: 


Under most circumstances, you 
should use these defaults. 


GLOBAL GBL Disabling this function causes 
MACRO-11 to treat all symbol 
references that are undefined at 
the end of assembly pass 1 as 
undefined symbols. The default is 
to treat all such symbols as 
global symbols. 


/(NO]SHOW[:(arg[,s])] 


These qualifiers override the .LIST and .NLIST assembler 
directives included in the source program being assembled. 
The .LIST and .NLIST directives control the content and 
format of the assembly listing. Table 3-3 summarizes the 
arguments to /SHOW and /NOSHOW and gives their MACRO-11 
equivalents. There is a default setting for each of these 
directives, even if you do not specify them in your code or 
command line. 


These qualifiers affect the entire assembly. ity fOr 
example, your MACRO command includes the qualifier 
/SHOW:COMMENTS, the assembly listing includes all comments, 
regardless of any -.NLIST COM or .LIST COM directives in the 
source code. The same goes for /NOSHOW:COMMENTS. All .LIST 
COM or .DISABL COM directives are ignored. 


Beat ao ei 


MACRO 


If you specify only one argument to /SHOW or /NOSHOW, you 


need not include the parentheses, 
they must be separated by commas and 
in parentheses. 


one argument, 


/SHOW implies /LIST, 


have a name 
Ji; LOe « 


other 


but 1£ you have more than 
enclosed 


but if you want the listing file to 
the default, you must still use 


Table 3-3: The /SHOW and /NOSHOW Qualifiers 


Function 


MACRO 
Syntax 


Description 


Listing Functions Disabled by Default 


EXPANSIONS 


BINARY 


LISTING. DIRECTIVES 


SEQUENCE__ NUMBERS 


COUNTER 


OBJECT. BINARY 


ME 


MEB 


LD 


SEQ 


LOC 


Enabling this function causes 
MACRO-11 to include all macro 
expansions in the listing. 


Enabling this function causes 
MACRO-11 to list only those 
macro expansions that generate 
binary code. This is a subset 
of EXPANSIONS. 


Enabling this function causes 
MACRO-11 to list all listing 
control directives without 
arguments (these are the 
listing directives that alter 
the listing level count). 


Disabling this function 
Suppresses the inclusion of 
sequence numbers in the 
listing. Sequence numbers are 
replaced by tabs. 


Disabling this function 
suppresses the location 
counter field and does not 
replace it with a tab. 


Disabling this function 
Suppresses the listing of 
generated binary code and does 
not replace it with a tab. 
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Function 


EXTENSIONS 


SOURCE 


COMMENTS 


DEFINITIONS 


MACRO 
Syntax 


BEX 


SRC 


COM 


MD 


MACRO 


Description 


Disabling this function 
Suppresses the listing of 
binary extensions, that is, 
all binary code that will not 


fit on the first line. 


This is 


a subset of OBJECT__BINARY. 


Disabling this 
Suppresses the 
source lines. 


Disabling this 
Suppresses the 
comments. This 
SOURCE. 


Disabling this 


Function 
listing of 


function 
listing of 
1s a subset of 


function 


Suppresses the listing of 
macro definitions and repeat 
range expansions. 
CALLS MC Disabling this function 
Suppresses the listing of 
macro calls and repeat range 
expansions. 
CONDITIONALS CND Disabling this function 
Suppresses the listing of 
unsatisfied conditional 
coding’; 
CONTENTS TOC Disabling this function 
Suppresses the listing of 
table of contents during 
assembly pass i. The full 
assembly listing is still 
prepared during assembly pass 
As 
SYMBOLS SYM Disabling this function 
suppresses the listing of the 
symbol table resulting from 
the assembly. 
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/{NO]WIDE 


Specifies whether you want the assembly listing in wide or 
narrow format. As supplied, the default is /WIDE, also 
called line printer format. /NOWIDE is sometimes called 
teleprinter format. 


This qualifier -overrides any <LIST. TIM ‘or .NLIST “TTM 
directives included in your source program. 


Parameter Qualifiers 
/PASS:n 


Specifies that the file thus qualified is only to _ be 
assembled during the pass specified. The assembler makes 
two passes; n can be either 1 or 2. 


/LIBRARY 


Specifies that the file thus qualified is a macro library. 
The default file type is .MLB. A user macro library file 
must be specified in the command line before any source 
files that use the macros defined in the library. A library 
may not be the last file named in the command line. 
Remember that the system macro library has the type .SML. 
If you are referencing this library, you must explicitly 
state the type. 
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3.47 MAIL 


With PRO/DECnet only, the MAIL command invokes the PRO/DECnet 
Maid: Uta bey: This utility allows you to send or read messages 
to or from other users on your system, or to another’ system 
connected by PRO/DECnet. For a complete description of the Mail 
Utility see the PRO/DECnet User’s Guide. 

Syntax 


MAIL 


Prompts 


None 


Qualifiers 


None 
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This command declares a volume (and therefore the files or data 
it contains) to be logically known to the system, on-line, and 
available for use. 
Syntax 

MOUNT([/qualifier] device: [volumelabel] 
qualifer 


Can be any combination of the following: 


/FOREIGN 
/ SHOW 


device: 
Is the device on which you want to mount the volume. 
volumelabel 
Is the name of the volume. If the volume name does not 
match the volumelabel parameter, then DCL displays an error 
message and does not mount the device. 
Prompts 
Device? device: [volumelabel ] 
Qualifiers 
/ FOREIGN 


Specifies that the volume being mounted is not in standard 
P/OS. CPILES=11.): format. 


/ SHOW 


Displays the volume label after mounting the volume. 
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3.49 PASCAL 


This command invokes the PRO/Tool Kit PASCAL compiler to compile 
one or more PASCAL source programs. 


NOTE 


Please refer to the language documentation for 
additional information. 


Syntax 

PASCAL[/qualifier[s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/{(NO]CHECK[:arg] 
ALL 
BOUNDS 
SUBRANGE 
POINTER 
STACK 
DIVIDE 
CASE 
YCODE<arg 
EPP 
EIS 
[NO ]DEBUG:TRACE_ BACK 
[NO]JLIST[:f1lespec] 
(NO]MACHINE_CODE[{:filespec] 
[NO]OBJECT[:filespec] 
[NO] STANDARD 
[NO ] 
[NO] 


fFilespec 
Is the name of a PASCAL source file. 


Prompts 


Files? 


j—4 


1 


mh 


espec([,Ss|] 


Baoan ew 


PASCAL 


Qualifiers 
/{NO]CHECK[ :arg] 


The /CHECK option controls run-time checking. 


Arguments: 

ALL enables all values (default) 

BOUNDS enables array bounds checking 

CASE enables CASE statement expression checking 
DIVIDE enables divide by zero checking 

POINTER enables NIL pointer checking 

STACK enables stack overflow checking 


SUBRANGE enables subrange checking 
{CODE !arg 


The /CODE option controls whether the code generated by Tool 
Kit PASCAL uses FPP instructions to perform floating point 
operations or EIS instructions to simulate floating point 
operations with subroutine calls. 


Arguments: 
FPP generates FPP instructions (default) 
EIS generates EIS instructions 


/([NO]DEBUG: TRACE BACK 


The /DEBUG option controls whether Tool Kit PASCAL generates 
code that tracks the relationship between the lines in the 
program source code and the current position in the 
executing program. When /DEBUG is enabled, run-time error 
messages indicate the line which caused the error and _ the 
currently active procedure and function invocations. 


/{NO]LIST[({:filespec] 


The /LIST[:filespec] option controls whether Tool Kit PASCAL 
generates a program listing file. The default is /NOLIST; 
thus compiler error messages appear on your terminal. siee 
you specify /LIST and do not supply a file specification, 
the default is file.LST, where file is the name of the first 
ADU. Les. 
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/([NO]MACHINE_CODE[:filespec] 


The /MACHINE_CODE option controls whether Tool Kit PASCAL 
generates a MACRO-11 source file containing the assembly 
language code EOr the program. The default is 
/NOMACHINE_CODE. 


The default name of the object file created by PASCAL is the 
last-named source file with the file type .MAC. If you want 
the object file to have a different name, supply the name as 
an argument to the qualifier. You can examine or assemble 
this file. 


Also, you must not specify the /OBJECT and /MACHINE_CODE 
qualifiers together on the same command line. 


/(NOJOBJECT[:filespec] 


Determines whether or not an object module is generated by 
the compiler. The default is /OBJECT, which does create a 
module’. The default name of the object file created by 
PASCAL is the last-named source file with the file type 
OBJ. If you want the object file to have a different name, 
supply the name as an argument to the /OBJECT qualifier. 


/NOOBJECT specifies that no object module is created. You 
can use the /NOOBJECT qualifier to get a compiler listing 


file to check for errors without generating object code. 


You must not specify the /OBJECT and /MACHINE_CODE 
qualifiers together on the same command line. 


/{NO]STANDARD 
The /STANDARD option flags any uses of language features not 
supported by the ISO PASCAL standard. The default is 
/NOSTANDARD. 

/{NO]XRAY or /[NO]LOG 
The /XRAY or /LOG option causes Tool Kit PASCAL to display 


its progress as it compiles a program. The default is 
/NOXRAY and /NOLOG. 


3-139 


3.50 PHONE 


With PRO/DECnet only, the PHONE command invokes the PRO/DECnet 
Phone Utility, which allows you to communicate with other users 
on your system or another system connected to your system by 
PRO/DECnet. For a complete description of the Phone Utility, 
including information on the PHONE command line, see the 
PRO/DECnet User’s Guide. 

Syntax 

PHONE [phone-command|] 
Prompt 


None 
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3.51 PRINT 


This command allows printing to the local printer. The 
default settings will be used to print the file(s). 
Syntax 

PRINT filespec[,s] 
filespec 


The name of the file(s) to print. 


Prompt 


File(s)? filespec[,s] 
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3.52 PRINT/REMOTE 


PRINT/REMOTE is available only with PRO/DECnet. PRINT/REMOTE 
directs an existing file on a remote node to a line printer for 
printing. If the file you want to print is not on that node, you 
may want to use the COPY command with a /PRINT qualifier. 


Syntax 

PRINT/REMOTE[/qualifier[,s]] filespec[,s] 
qualifier | 

Can be one or more of the following: 


JLOG 
/{NO]WARNINGS 


filespec 


The file specification (including node specification) for 
each file to be queued for printing. 


Prompt 


File(s)? filespec[,s] 


Qualifiers 


/ LOG 


The /LOG qualifier specifies that the names of files printed 
are to be displayed as the operation is performed. 


/{NO]WARNINGS 


The /NOWARNINGS qualifier specifies that the "No such file" 
error messages should not be displayed when the input files 
do not exist. 


Example 


S PRINT/REMOTE/LOG MYFILE.DOC <DO> 
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3.53 PURGE 


PURGE deletes all but the latest versions of files, and releases 
the storage space that the deleted files occupied. 


Syntax 
PURGE[/qualifier[s]] filespec[,s] 
qualifier 
Can be one or more of the following: 
/{[NO]LOG 
/KEEPin 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 
/EXCLUDE: filespec 
/NOWARNINGS 


filespec 


Is the name of the file, whose old versions are to _ be 
deleted. You must have delete access to the file. 


Prompts 

File(s)? filespec[,s] 
Qualifiers 
/{NO]LOG 


Specifies that the files deleted by PURGE be listed on your 
terminal. The default is /NOLOG. 


/KEEP:n 
Specifies that the n latest versions of a file be retained. 


If you do not use this qualifier, all versions but the most 
recent of a given file are deleted. That is, the default 


form of the command includes the qualifier /KEEP:1. With 
the qualifier explicitly stated, all but then highest 
numbered versions are deleted. PURGE assumes that the 
version numbers of files are in sequential order, for 
example: 
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PIDELelISs4 FILE. bIS;3° PRGEIL~GI1S 2 FILE? iiss i 


and that there are no versions missing from the sequence, 
for example: 


FIBELs DiS 720 FPILELsbiSe1S- Prbel BiSei4 


If more than one filespec is given with the /KEEP qualifier, 
all but the latest n versions of all files listed are 
deleted. 


/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the PURGE 
command to affect only files created by the value specified 
for /DATE. 


/SINCE:dd-mmm-yy 


The /SINCE gualifier specifies that you want the PURGE 
command to affect only files created on or since the value 
specified by /SINCE. 


/THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that you want the PURGE 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the PURGE command to affect only files 
created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the PURGE 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that you want the PURGE 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 
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/NOWARNINGS 
The /NOWARNINGS qualifier specifies that the "No such file" 


error message should not be displayed when the input files 
do not exist. 
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3.54 REMOVE 


This command removes the name of a task from the System Task 
Directory. The task is no longer installed. REMOVE/REGION takes 
the name of a region out of the Common Block Directory and _ the 
DarllGlom A26t. 


Syntax 
REMOVE[/qualifier] taskname 

qualifier 
/ REGION 

taskname 
Is the name of the task to be removed from the System Task 
Directory. If you want to remove a region, specify the 
/REGION qualifier. 

Prompts 
Taskname? taskname 

Qualifier 

/ REGION 


Specifies that you want to remove a region from the Common 
Block Direcrory. 
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3.55 RENAME 


This command changes the name, type, or version number of an 
existing file. 


Syntax 
RENAME[/qualifier[s]] old_filespec new_filespec 
qualifier 
Can be one or more of the following: 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 
/EXCLUDE:filespec 
/NOWARNINGS 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


/LOG 
/NEW_VERSION 

old_filespec 
is the filename prior to renaming. 

new_filespec 
Is the desired new name of the file. If you want to specify 
a new directory for the file, you can only specify a 
directory that exists on the same volume. This is _ because 
the file is not actually copied. 


Prompts 


Old file name? old_filespec 
New file name? new_filespec 
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Qualifiers 

/DATE:dd-mmm-yy 
The /DATE qualifier specifies that you want the RENAME 
command to affect only files created by the value specified 
ror / DATE. 

/SINCE: dd-mmm-yy 
The /SINCE qualifier specifies that you want the RENAME 
command to affect only files created on or since the value 
specified by /SINCE. 

/THROUGH: dd-mmm-yy 
The /THROUGH qualifier specifies that you want the RENAME 
command to affect only files created on or before the value 
specified by /THROUGH. 

/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 
The /SINCE and /THROUGH qualifiers can be combined to 


specify that you want the RENAME command to affect only 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the RENAME 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 
The /EXCLUDE qualifier specifies that you want the RENAME 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 


contain a version number, either explicitly or as the "*" 
wildéard.: 


/NOWARNINGS 


Specifies that the "No such file" error messages should not 
be displayed when the old_filespec does not exist. 
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Additional Qualifiers Available with PRO/DECnet 
Command Qualifiers 
/ LOG 


Specifies that the names of files renamed are to be 
displayed as the operation is performed. 


File Qualifiers 
/NEW_VERSION 


The NEW_VERSION qualifier specifies that the output files 
will be created with a version number higher than any 
existing files of the same name in the GLreceory. 
/NEW_VERSION must appear after the file specification in the 
command line. 
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3.56 RUN uninstalled task 


This command checks to see if the task is installed. If the task 
is not installed, RUN installs the task image, runs it, and 
removes the name of the task from the System Task Directory when 
task execution completes. In the case when a task image is not 
installed, RUN actually comprises the INSTALL, RUN, and REMOVE 
commands. 


Syntax 

RUN[/qualifier[{s]] [S$] filespec 
qualifier 

Can be one or more of the following: 


/COMMAND: "taskcommand" 
/TASK_NAME:taskname 


[S$] filespec 
Is the name of the uninstalled task image. The dollar sign 
(S$) directs the system to search first for the file in the 


PRO/Tool Kit application directory. You can display this 
directory by typing SHOW LOGICAL APPLSDIR. 


Prompts 
Task? [S$]filespec 
Qualifiers 
/COMMAND: "taskcommand" 
Use the /COMMAND qualifier to pass a command to the task you 


are running. The command must be inside the "quotes" and 
not more than 40 characters long. For example, the command 


RUN/COMMAND: "PIP /LI" SPIP 


runs PIP and then passes the /LI qualifier to it. This 
results in a directory listing. 


To pass an MCR-format command (if the task will accept it), 
you must precede the command with the taskname followed by a 
Space. For example: 


RUN/COMMAND: "CMP TI:=filel.dat,file2.dat" SCMP 
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/TASK_NAME:taskname 


Specifies the name under which the task is to be run. The 
default 1s to run the task under a name derived from the 
name of the terminal from which the RUN command was issued. 


Task names are restricted to six Radix-50 characters. The 
Radix-50 character set consists of the 26 uppercase letters, 
the 10 numerals, the period (.), and dollar sign (S$). 
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3.57 RUN installed task 


Tf the task is installed, RUN initiates its execution. You can 
use RUN to initiate the execution of installed tasks ona 
schedule by creating entries in the system clock queue. 


Syntax 


RUN[/qualifier[s]] taskname 
qualifier 

Can be one or more of the following: 

/COMMAND: "taskcommand" 

/DELAY :nu 

/INTERVAL : nu 

/SCHEDULE: hh:mm:ss 

/SYNCHRONIZE:u 


taskname 
Is the name of the task that RUN will execute. 
Prompts 
Task? taskname 
Qualifiers 
/COMMAND: "taskcommand" 
Use the /COMMAND qualifier to pass a command to the task you 


are running. The command must be inside the "quotes" and 
not more than 40 characters long. For example, the command 


RUN/COMMAND: "PIP /LI" SPIP 


runs PIP and then passes the /LI qualifier to it. This 
results in a directory listing. 


To pass an MCR-format command (if the task will accept it), 
you must precede the command with the taskname followed by a 


Space. For example: 


RUN/COMMAND: "CMP TI:=filel.dat,file2.dat" SCMP 
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The time-oriented qualifiers to RUN create entries in the system 
clock queue. The contents of the clock queue can be displayed 
with the command SHOW CLOCK QUEUE. 


/DELAY:nu 


Specifies that the task be run after the stated amount of 
time passes. The argument nu specifies the amount of the 
delay as a number of units. The value nis the number of 
units and the value u is the time unit, as follows: 


T - Ticks 
S - Seconds 
M - Minutes 
H - Hours 


Your system has a programmable clock. The frequency of this 
clock is 64 Hz, which results ina tick length of 1/64th of 
a second. 


Acceptable values for these units are as follows: 


T - Any positive value to a maximum of 15 bits, or 
S210). 

S - Any positive value to a maximum of 15 bits, or 
52167 5 


M - The maximum value is 1440. 


H The maximum value is 24. 
The system always waits at least one interval. If you 
specify 0). the system treats: 1 as: atx 


/INTERVAL: nu 


Specifies that the task is to be run at regular intervals. 
The argument nu specifies the interval as a number of units 
of time. The value n is the number of units and the value u 
is the unit, as follows: 


T - Ticks 
S - Seconds 
M - Minutes 
H - Hours 


See the /DELAY qualifier for a detailed description of these 
units. 
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/SCHEDULE:hh:mm:ss 

Specifies that the task be run at a particular time of day. 
/ SYNCHRONIZE: u 

Specifies that the execution of the task be synchronized on 


the next occurrence of a particular clock unit. The value u 
is the time unit, as follows: 


TY de SCI 
S - Seconds 
M - Minutes 
H - Hours 
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3.58 SET [DAY]TIME 


This command sets the current date and time. 
Syntax 

SET [DAY]TIME:[dd-mmm-yy] [hh:mm] 
dd-mmm-yy 


Specifies the date. You can enter the date in either of two 
formats: 


dd-mmm-yy Where dd is the number of the day, mmm is 
the first three characters of the name of 
the month, and yy is the number of the 
year (relative to 1900). 


mn/dd/yy Where mn is the number of the month, dd is 
the number of the day, and yy is the 
number of the year (relative to 1900). 


Regardless of the format you choose, the date is displayed 
in the first. format. 


hh:mm[:ss] 


Is the time to which the system will be set (24-hour format) 
in the form 14:35. 


Prompts 


Time? hh:mm 
Date? dd-mmm-yy 
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3.59 SET DEFAULT 


The SET DEFAULT command establishes the default directory and/or 
device from the current default. You can set the default for the 
directory, the device, or both. 


It is possible to set default to a nonexistent dévice or 
directory.; no error is reported when the SET DEFAULT command 1s 


executed. However, an error is reported when you try to perform 
an operation in the nonexistent directory or on the nonexistent 


device. 
Syntax 

SET DEFAULT [device: ][dirspec] 
device: 


Is the device name. 


dirspec 
is the directory name enclosed in square brackets, for 
example: [MYDIR]. 

Prompts 
Device and/or directory? (device: ][dirspec] 
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3.60 SET DEVICE 


SET DEVICE establishes certain attributes for the specified 
device. 


Syntax 
SET DEVICE:ddnnn: /device-attribute[s] 


ddnn 


Specifies the device for which attributes are to be _ set. 
When the one-line form of the command is used, the parameter 
is ddnnn: preceded by a colon (:) at the end of the word 
DEVICE « 

device-attribute 


Can be one or more of the following: 


/ [NO] LOWERCASE 
/WIDTH:n 


Prompts 


Device? ddnnn: 
Device attribute? qualifier 


Device Attributes 

/{NO]LOWERCASE 
The /LOWERCASE attribute sets a terminal or line printer so 
that lowercase characters are not converted to uppercase for 
printing. 
The /NOLOWERCASE attribute sets a terminal or line printer 
so that lowercase characters are converted to uppercase for 


primnting.. This: as the-default. 


You can use the SET TERMINAL/LOWERCASE command to set TI: 
in this fashion. 


/WIDTH:n 


Sets the size of a device’s I/O buffer. The value of nn 
(octal) is the length in characters of a line on the device. 
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For terminals, n must be greater than 2 and not greater than 
ZOD The terminal driver does not discard excess 
characters, but puts them in a record of their own. That 
1s, excess characters appear one line below the line in 
which they should appear. 
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3.61 SET HOST 


With PRO/DECnet only, SET HOST invokes the Remote DECnet Terminal 
application (available with PRO/DECnet). This allows your 
Professional node to communicate with a remote host, performing 
terminal operations as though it were local to the host. The 
host must support terminal emulation from remote nodes. 
Syntax 

SET HOST node_name 


node-name 


Is the name of the node to which you want to connect. 


Prompts 


Host? node_name 


Qualifiers 

None 
To disconnect from a VMS or RSX host computer, either log off of 
the host, or press the <MAIN SCREEN> or <EXIT> key. The 


preferable method is to log off the host computer. 


To disconnect from a TOPS-10 or TOPS-20 host computer, log off of 
the host, and then press the <MAIN SCREEN> or the <EXIT> key. 


Once you have exited from the host computer, press <RESUME> to 
return control to your node. 


Refer to the PRO/DECnet User’s Guide for information about 
differences in processing during terminal emulation. 
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3.62 SET PRIORITY 


This command alters the priority of an active task. 


Syntax 


SET PRIORITY:n taskname 


Specifies the new priority you want to assign to the task. 
Priority mumbers are in the range of from 1 through 250. 
The value n is octal or decimal. Append a decimal point to 
indicate that it is a decimal number. 


taskname 


Is the name of the task whose priority is to change. 


Prompts 


Priority number? n 
Taskname? taskname 
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3.63 SET PROTECTION 


SET PROTECTION establishes the protection status of ae file. 
Protection status determines which categories of user may access 
a file and what each kind of user may do to the file. 
Syntax 

SET PROTECTION[/qualifier[{s]] filespec[,s] (code) 
qualifier 

Can be one or more of the following: 

/DATE:dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 

/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 

/TODAY 

/EXCLUDE: filespec 

/([NO]WARNINGS 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


/OWNER[ :ulc] 


filespec 
Is the name of the file to be protected 
(code) 
There are four kinds of users: 
SYSTEM The operating system itself, and 


privileged users, those with group 
numbers of 10 or less. 


OWNER The user whose UIC the file was created 
under. 
GROUP All users whose group number the file was 


created under. 
WORLD All other users. 


There are also four kinds of access to files: 
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READ The user or user’s tasks can read, copy, 
print, ““yoer Or pum the file {af 26. 16.4 
task image). 


WRITE The user or user’s taskS can write new 
data to the file. 


EXTEND The user or user’s tasks can increase the 
amount of disk space allocated to the 
file. 

DELETE The user or user’s tasks can delete the 
file. 


The system default protection code is expressed as follows: 


(SYSTEM: RWED,OWNER: RWED, GROUP: RWED,WORLD: RWED) 


Under this code, the system and privileged users have full 
access to your files, You, as well as others with your group 
number, also have full access to your files. Other 
nonprivileged users can only read your files. If no other 
protection is specified, all files have this protection. 


If you want to protect a particular file differently from 
the current system default, name in the protection code only 
the user group whose access rights you want to change and 
the access form you want to grant to that group. If you 
want to deny all access to a group, simply name the _ group 
and omit the colon (:) and the code for the access form. 


If any of the parameters (System, Owner, Group, World) is 
eliminated from the code, SET PROTECTION does not change the 
value of that parameter. If the parameter is listed with no 
code (SYSTEM:R,OWNER: RWED,GROUP,WORLD), SET PROTECTION 
assigns no access to that parameter. 

Prompts 
File? filespec([,s] 

Qualifiers 

/DATE:dd-mmm-yy 
The /DATE qualifier specifies that the SET PROTECTION 


command affect only files created by the value specified for 
/DATE. 


se1 02 
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/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that the SET PROTECTION 
command affect only files created on or since the value 
specified by /SINCE. 

/ THROUGH: dd-mmm-yy 


The /THROUGH qualifier specifies that the SET PROTECTION 
command affect only files created on or before the value 
specified by /THROUGH. 

/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
The /SINCE and /THROUGH qualifiers combined specifies that 
the SET PROTECTION command affect only files created within 
the given range. 


/ TODAY 


The /TODAY qualifier specifies that the SET PROTECTION 
command affect only files created on the day the command is 
issued. 

/EXCLUDE: filespec 
The /EXCLUDE qualifier specifies that you want the _ SET 
PROTECTION command not to affect certain files. The 
fFilespec argument to /EXCLUDE can contain wildcards, but the 
filespec must contain a version number, either explicitly or 
as the "*" wildcard. 

/NOWARNINGS 


This qualifier suppresses display of "No such file" error 
messages when the input files specified do not exist. 


Additional Qualifiers Available with PRO/DECnet 
Command Qualifiers 

None 

File Qualifiers 

/OWNER:uic 


Sets the ownership of a file to the specified UIC, in _ the 
form [ggg,mmm]. 
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3.64 SET PROTECTION/DEFAULT 


Establishes the default protection for all files 


the current login session. The protection for a file 
type of access available to other system users. 


Syntax 


SET PROTECTION: protection_code/DEFAULT 


protection_code 


created during 


limits the 


Is the protection code to be given to the files created 
during your current Login séssion. 


The code takes the following format: 


CTSYSTEM/(2m]+,1OWNER( 1) | {(GROUP[ 2n) ), [WORLD sm} }) 


where: 
SYSTEM Is 
OWNER Is 
GROUP Is 
WORLD Ls 
n Ls 


the 


the 


the 


the 


the 


system level protection code. 
owner level protection code. 
group level protection code. 


world level protection code. 


type of access that is to be allowed. 


The value for n can be any or all of the following values, in any 


order: 


R Read allowed. 
type ‘(scroll through) ‘the tite, and: 12 2%. 28 <a 
task,. PUn..4/t< 


W Write allowed. 
application) can add new information to the file. 


The user may read, copy, print or 


The user (or the user’s 


The user, or the user’s tasks, 


change the amount of disk space allocated to 


E Extend allowed. 
the file. 
D Delete allowed. 


application) 


The user (or the user’s 


can delete the file. 


Can 


Only those categories that are specified are allowed; all others 


remain protected. 


fen 


you enter one of the categories, 
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SET PROTECTION/DEFAULT 


specify a value for n, no access is allowed at that level. In 
addition, if a category is not entered, then access is denied for 
that category. For example, SET DEFAULT PROTECTION: (OWNER: RWED) 
allows only owner access to the files created. 


NOTE 
Your default file protection is set during the 
login process. You may specify a default file 
protection that is restored during the login 
process with Environment Services. 


Prompts 


Protection code? protection_code 
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3.65 SET PROTECTION/NODEFAULT 


Removes, your currently defined default file protection. (See 
SET PROTECTION/DEFAULT.) Any file created during the current 
login session will have the file protection of: 

(SYSTEM: RWED, OWNER: RWED, GROUP: RWED, WORLD: RWED) 
Syntax 

SET PROTECTION/NODEFAULT 


Prompts 


None 
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3.66 SET TERMINAL 


This command sets various attributes of the terminal. 
Syntax 

SET TERMINAL[:ttnnn:] attribute[/attribute[s]] 
ttnnn 

Is the number of the terminal. 
attribute 

Can be one or more of the following: 

Group 1: Common Use 


/ {NO ]LOWERCASE /{NO]UPPERCASE 
/WIDTH:n 


Group 2: Terminal Setup 


/VT100 /VT101 

/VNT102 JNEIOS 

YVELZS J VTLS 

JN TL 32 INTIA 

/LASO /LALOO 

/LA210 /LQOPO2 

fPC300 /{NO]FORM_FEED 

/({[NO]TAB /({NO]HARDCOPY 

/({[NO]SCOPE /PAGE_LENGTH:n 
Group 3: Task Setup 

/(NO]ECHO /([NO]ESCAPE 

/{[NO]TYPEAHEAD[ :n] /{NO]WRAP 


/{NO]EIGHT_BIT 


Prompts 
Terminal Attribute? attribute[/attribute[s]] 


You can set several attributes at once. If one of these commands 
fails, all others following it in the command line also fail. 
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Group 1s Common Use 


The following parameters set terminal characteristics that 


are regularly needed by the average terminal user. 
/{NO]UPPERCASE 
/UPPERCASE is the default. All 


terminal appear in uppercase. 
/UPPERCASE. 


Characters typed on the 
/NOLOWERCASE is the same as 


/{NO]LOWERCASE 


Characters typed on the terminal in lowercase appear in 


lowercase. Most system tasks will accept input in 
lowercase. Note that some terminal escape sequences use 
lowercase characters. If, for instance, the keypad commands 


in EDT do not seem to be working, you may have to set the 
/LOWERCASE attribute. 


/WIDTH:n 
The SET TERMINAL/WIDTH command sets the width of your 
terminal, that is, the length of a line. The value n can 


range from 0 through 132. Note that a line length of zero 


means no commands can be entered on the terminal. 
Group 2: Terminal Setup 
The following qualifiers set hardware characteristics of 


terminals. For certain common models, you can set a number 
of characteristics automatically simply by identifying the 


model. For other terminals, you must set these 
characteristics expliciciy. 
Here are the models for which setup is provided: 

VT100 VP). 

VTLOZ VTLOS 

VEZ 5 ‘VE Eo 

VILs2 VT2XX 

LA50 LA100 

LA210 LOPQ2 

PC300 
All of these are DIGITAL terminals. Those with "LA" 
designations are hard-copy terminals; those with "VT" and 


"PC" designations are video models. 
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Setting a terminal to a particular model does not mean 


that 


the terminal will behave like that model. It means only 


that the operating system will treat the terminal as if 


aes 


were that model. This feature is intended primarily to 


deceive tasks that expect a certain terminal model or 


identify a terminal as to what it is. 


LO 


You can set hard-copy terminals as video terminals and you 
can set video terminals as hard-copy terminals. For the 
terminal user, the most noticeable difference will be in the 


way the DELETE key operates. setting terminals 


from 


hard-copy to video may prove disruptive; setting terminals 


From video to hard-copy is less likely to cause trouble. 


Setting a terminal to a particular model designation 
automatically sets a number of attributes for the terminal. 


You can also set these attributes individually. 


You can find out how your terminal is known by issuing a 
SHOW TERMINAL command. 
NOTE 
The DCL single line editor does not honor the ECHO, 
LOWER, WRAP, or WIDTH terminal attributes. 
/ NOHARDCOPY 
{SCOPE 
Sets the terminal as a video terminal. /SCOPE is the 
equivalent of /NOHARDCOPY. 
/HARDCOPY 
/NOSCOPE 
Sets the terminal as a hard-copy terminal. /NOSCOPE 1s the 
equivalent of /HARDCOPY. 
/{NO]FORMFEED 
If the terminal hardware supports form feeds, the terminal 


should be set /FORMFEED. If form feeds are handled by the 


software providing line feeds, the terminal should be 
/NOFORMFEED. 
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/{NO]TAB 


If the terminal hardware supports horizontal tabs, the 
terminal should be set’ TAB. If tabs are handled by the 
software providing spaces, the terminal should be set NOTAB. 


/PAGE_LENGTH:n 


Defines the number of lines to a_ page. By convention, a 
page is usually considered the number of lines to a 
screenful on video terminals or the number of lines between 
perforations on hard-copy terminals. This attribute sets 
the length of the page. 


Group 3: Task Setup 


The following parameters set terminal characteristics that 
may be needed by system or user tasks. Most system tasks 
that require these attributes ina terminal will set the 
attributes when they attach the terminal. User tasks can 
also do this. This will be transparent to the user. These 
parameters are included for use in cases where the task does 
not do this setting. 


/{|NO] ECHO 


Enables (or disables) echoing of characters typed on _ the 
terminal. 


/ECHO is the default. Characters typed on the terminal are 
echoed on the terminal. 


/NOECHO suppresses the echo. 


/NOECHO changes nothing but echoing. Commands can still be 
passed to the system, but the system passes no echo back. 


/{NO]ESCAPE 


Enables (or disables) recognition of escape sequences froma 
terminal. 


/NOESCAPE is the default. When you press the ESC key 
(equivalent to CTRL/3 on LK201 keyboards), it is interpreted 
as a line terminator (with a line feed but no carriage 


return). 


ESCAPE enables the recognition of escape sequences from the 
terminal. When you press the ESC key, it is interpreted as 
the beginning of an escape sequence. The ESC key will no 
longer terminate a line. 
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This is a rarely used parameter. Most tasks that recognize 
escape sequences will attach the terminal so that escape 
sequences are passed without the user’s knowledge, usually 
from the keypad. 


/ [NO ]WRAP 


Specifies that the terminal automatically wrap (or not wrap) 
lines longer than its line width. 


/WRAP is the default. The terminal automatically issues a 
Carriage return and a line feed when you type to whatever 
line width the terminal is set for. 


/NOWRAP overrides this feature and permits unlimited line 
length. 


/{NO]EIGHT_BIT 
Enables (or disables) a terminal’s /EIGHT_BIT attribute. 


/EIGHT_BIT is the default, because the Professional 350 uses 
eight bit mode to display the DEC Multinational Character 
Set. /EIGHT_BIT allows the terminal to pass all eight bits 
of the ASCII character. This attribute is used when your 
terminal is communicating with some device that sends 68-bit 
ASCII. 
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3.67 SHOW ASSIGNMENTS 


SHOW ASSIGNMENTS displays all the logical names in the logical 
mame table(s), or it displays the current equivalence value 
assigned to a specific logical name. 
Syntax 

SHOW ASSIGNMENTS[/qualifier[s]] [logical_name] 
qualifier 

Can be any combination of the following: 

/USER 

/ SESSION 

/SYSTEM 

J Rash 


logical_name 


Is the name of a unique logical assignment. 


Prompts 

None 
Qualifiers 
/ALL 


Specifies that all logical names in the specified logical 
name table(s) be displayed. 


/USER 
Limits the search to the user logical name table. 


/SESSION 


Limits the search to the session logical name table. If you 
do not explicitly ‘specify a logical name table, P/OS uses 
/SESSION by default. 


/SYSTEM 


Limits the search to the system logical name table. 
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3.68 SHOW CLOCK QUEUE 


SHOW CLOCK_QUEUE displays information about tasks that are 
currently in the clock queue. The displayed information 
comprises task names, the next time the task is scheduled to run, 
and each task’s reschedule interval, if any. 
Syntax 

SHOW CLOCK_QUEUE 
Prompts 


None 


3-173 


SHOW COMMON 


3.69 SHOW COMMON 


SHOW COMMON displays the names of resident commons installed in 
the system, their PCB addresses, the number of attached tasks, 
and the status of the common. 

You can also display information about a Single common; 
optionally, you can include a list of tasks attached to the 
common. 


If you do not name a common, information about all commons in the 
Common Block Directory is displayed. 


Syntax 

SHOW COMMON[:name][/qualifier] 
qualifier 

/ TASK 
name 

Is the name of the common. 
The display is in the following format: 

commonname pcbaddr taskcount statusbits 

In the format that SHOW COMMON displays at the terminal, 
commonname is the name of the common, pcbaddr is the address of 
the Partition Control Block (PCB), taskcount is the number of 
tasks mapped to the common, and statusbits is a list of common 
region status bits that are set. Usually, the status bits will 


indicate that the common region is either fixed in memory (FXD) 
or Out of. memory: (OUT). 


Table 3-4 lists the status bits and their meanings. 
Prompts 
None 
Qualifier 
/TASK 
Specifies that you want a 1list of tasks attached to a 


particular common region showing the number of times each 
task is mapped to the common (mapping count). 
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Table 3-4: Status Bits 


Status Bit Meaning 

CAF Checkpoint allocation failure 
-~CHK Not checkpointable 

CKP Checkpoint in progress 

CKR Checkpoint requested 

COM Library or common 

DEL Marked for delete on last detach 
DRV Driver common 

FXD Fixed in memory 

LIO Long I/0 

LFR Last load failed 

NSF | Not shuffleable 

OUT Out of memory 

PER Parity error 

PIC Position independent 

RON Read-only common 
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3.70 SHOW DAYTIME or SHOW TIME 


This command displays the current day and time. 
Syntax 
SHOW DAYTIME 
or 
SHOW TIME 
Prompts 


None 
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3.71 SHOW DEFAULT 
This command displays the current default 
name. 
Syntax 
SHOW DEFAULT 


Prompts 


None 
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3.72 SHOW DEVICES 


This command displays information concerning the devices that are 
included in the system. 


Syntax 
SHOW DEVICES[/qualifier] 
qualifier 
Can be one or more of the following: 


/ad[nnn]: 
/WIDTH:ddnnn: 


Prompts 
None 


If you do not include a qualifier, SHOW DEVICES displays a list 
of all the devices on the system, including terminals. 


Qualifiers 

/dad[nnn]: 
Displays information about all devices of a particular type 
on the system. The value of dd: is a two-letter device 
mnemonic terminated with a colon, which indicates the type 


of device controller. The display shows the devices under 
that type of controller by model name. 


/WIDTH:ddnnn: 


Displays the size of the I/O buffer (line length) for a 
particular device, including a4 terminal. 
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3.73 SHOW LOGICALS 


SHOW LOGICALS displays all the current logical names in the 
logical name table(s), or it displays the current equivalence 
value of a specific logical name. 
Syntax 

SHOW LOGICALS[/qualifier[s]] [logical_name] 
qualifier 

Can be any combination of the following: 

/USER 

/SESSION 

FSCS UEM 

/ALL 


logical_name 


Is the name of a unique logical assignment. 


Prompts 

None 
Qualifiers 
JRLL 


Specifies that all logical names in the specified logical 
name table(s) be displayed. 


/USER 
Limits the search to the user logical name table. 

/ SESSION 
Limits the search to the session logical name table. If you 
do not explicitly specify a logical name table, P/OS uses 


/SESSION by default. 


foi oleM 


Limits the search to the system logical name table. 
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3.74 SHOW MEMORY 


SHOW MEMORY invokes the Resource Monitoring Display (RMD), a 
system utility program. This program displays ina graphic 
manner the status of much of the system. 


The RMD program is useful for monitoring the general activity of 


the system. It is also useful for a new user to see how the 
operating system operates. However, you should understand that 
the graphic display iS approximate and cannot be used for 
critical measurement. (Refer to Chapter 8 for a description of 
RMD. ) 

Syntax 


SHOW MEMORY 
Prompts 


None 
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3.75 SHOW PROTECTION 


SHOW PROTECTION displays the current file protection to be 
applied to all new files created during the current session. You 
can change the default protection at any time using the SET 
PROTECTION/DEFAULT command. 
Syntax 

SHOW PROTECTION 
Prompts 


None 
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3.76 SHOW TASKS/ACTIVE 


SHOW TASKS/ACTIVE displays information about active tasks in 
brief and full format. 


Syntax (Brief Format) 
SHOW TASKS /ACTIVE[ :ttnnn: ][/qualifiert[s]} 

ttnnn: 
If you name a terminal in the command, the display shows in 
briet form the: tasks active @t that. terminal, . Tf you. de not 


mame a terminal, the display shows in brief form the tasks 
active at your terminal. 


qualifier[s] 
Can be one or more of the following: 


/BRIEF 
eae 


Qualifiers 
/BRIEF 


Specifies that you want to display information about active 
tasks in the brief format. This is the default and need not 


be specified. 


The brief format includes task. names and. the ‘originating 
terminal in parentheses next to each task name. 


WALL 
Specifies that you want to display information about all 


tasks active on the system. The default is to show 
information about tasks active at your terminal only. 


Syntax (Full Format) 
SHOW TASKS/ACTIVE/FULL [taskname ] 


SHOW TASK[ :taskname]/ACTIVE/FULL 
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taskname 
If you include a task name, the display shows Pid 
information on that task. If you do not name a task, the 
display shows full information on all currently active 
tasks. 

Qualifiers 

/FULL 


Requests the full format display for the SHOW TASK/ACTIVE 
command. This format includes detailed information on the 
state of one or all tasks active on the system. The format 
of the display is as follows: 


taskname tcbaddr parname pcbaddr taskaddrlimits pri defpri 

STATUS: statusflags 

TI - ttnnn: IOC - 1ocount BOC -buffiocount EFLG -eventflags PS -pswv 
PC - pcval REGS 0-6 rival r2val r3val r4val r5val r6val 


Table 3-5 describes the items that appear in the display. 
If the task is not in memory, the PC, PSW, and other 
registers are not displayed. 


The display shows the state of the task at the time the 
command was issued. You can display similar information 
dynamically (in real time) for a single task with the 
/DYNAMIC qualifier, as explained in Section 3.78. 


Table 3-5: Display for SHOW TASKS/ACTIVE 


Item Description 

tcbaddr The physical address of the Task Control 
BLOCK. (TCB). 

parname The name of the task’s partition. 

pcbaddr The physical address of the Partition 
Control Biock -CPCB). 

taskaddrlimits The base and top of the task’s dynamic 
subpartition as physical addresses. 

op aul The priority at which the task is actually 
Puna. 
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defpri 
STATUS 

lee 

TOC 

BIO 

EFLG 

pswval 

peval 

REGS 

Table 3-6: 

Status TCB 

Flag Fla 
ABO ey 
ACP 3s 
AST TT 
BLK cS. 
CAF 2 
CAL To 3 
~CHK gigs 
Cie TS 
CKD Ts 
CKP LS 
CKR alge’ 
CLI T3 
DST 2 
-~EXE LD% 
FXD Wee 
GFL ale: 


SHOW TASKS/ACTIVE 
The default priority at which the task was 
built or installed to run. 


The task’s status LLaAgsS : These are 
identified in Table 3-6. 


The initiating terminal. 
The decimal I/O count for the task. 


The decimal count of I/0 buffered by the 
terminal driver and Executive. 


Local event flags. 

The Processor Status Word. 

The Program Counter. 

The contents of the task’s other registers. 


If the task was spawned by another task, the 
name of the parent task is also displayed. 


Task Status Flags 


g 


- ABO 


ACP 


‘Ask 


SEP 


. CAF 


CAP 


2CHK 
,CLE 
- CKD 
KCKE 
CK 
maa nye 
OSE 


BX E 
EXD 


SEs 


Meaning 


Being aborted 

Ancillary Control Processor 

AST state 

Blocked externally by CLI command 
Dynamic checkpointing allocation failure 
Checkpoint space allocated in task image 
Not checkpointable 

Blocked for checkpoint in progress 
Checkpointing disabled 

CneckpoOLiced 

Checkpoint request pending 

Command Line Interpreter 

ASTs disabled 

Not executing 

Fixed in memory 

Task has own group global event flags locked 
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Status 
Flag 


-PMD 
OUT 
PRV 
RDN 
REM 
REX 
ROV 
RST 
SEF 
SLV 
SPN 
SPNA 
SIP 
STPA 
SWS 
WFR 
WFRA 
DSP 
LDD 
MUT 
PRO 
PRV 
SNC 


SHOW TASKS/ACTIVE 


TCB 
Flag Meaning 


T3.PMD Suppress PMD on SST abort 

TS.OUT Out of memory 

T3.PRV Privileged 

T3.RDN 1/0 being run down 

T3.REM Remove on exit 

T2.REX Abort AST effected or in progress 
T3.ROV Resident overlays 

T3.RST Restricted - used by layered software 
T2.SEF Stopped for event flag 

T3.SLV Slaved 

T2.SPN Being suspended 

T2.SPN Suspended prior to AST 

TZ2.STP Stopped 

T2.97TP . Stopped: pricr to AST 

T3.SWS Reserved for software services 
T2.WFR Ina wait-for state 

T2.WFR Ina wait-for state prior to AST 


T4.DSP Task was built for user-mode I- and D-space 


T4.LDD Task’s load device has been dismounted 
T4.MUT Task is multiuser task 

T4.PRO Task is (or should be) a prototype task 
T4.PRV Task was privileged but has cleared T3.PRV 
T4.SNC Task uses commons for synchronization 


NOTE 


These status flags are displayed by several forms 
of the SHOW TASK command. They give information 
on what is happening within the task and between 
the task and the system. They also identify 


certain kinds of tasks. Names prefixed by a 
minus (-) indicate the complement of the 
condition. Thus, -CHK means the task is 
noncheckpointable. You must understand how the 
system runs tasks to understand the meanings of 
all these flags. See the RSX-11M/M-PLUS and 


Micro/RSxX Task Builder Manual and the P/OS System 
Reference Manual for more information. 
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3.77 SHOW TASKS/INSTALLED 


SHOW TASKS/INSTALLED displays information about installed tasks 
in either brief or full format. 


Syntax 
SHOW TASKS[:taskname]/INSTALLED[/qualifier[s]] 
taskname 


Specifies the task for which you want information displayed. 
If you do not specify a task name, information on all 
installed tasks is displayed. 


qualifier([s] 
Can be one or more of the following: 


/BRIEF 
JFULL 


Qualifiers 
/BRIEF 


Requests information on installed tasks ina brief format. 
This is the default and need not be specified. The format 
of the display is as follows: 


taskname ident parname priority size ddnnn:-lbn [memstate] 


In this display, taskname is the name task, ident is the 
task version identification (or the version of the prototype 
task), parname is the partition in which the task is 
installed, priority is its priority, size is the size of the 
task in bytes, ddnnn: is the device from which it is to be 
loaded, lbn is the logical block number of its disk address, 
and memstate is the task memory state, which can be FIXED, 
CHECKPOINTED, or blank. 


If the task version identification is missing (with the rest 
of the line moved left) or if it is garbage, the task was 
installed from a disk that is no longer’ present. If the 
task version number is a date, such as O7JUL, the task was 
compiled on that day. 
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SHOW TASKS/INSTALLED 


Requests the full format of the SHOW TASKS/INSTALLED 
command. This format displays a detailed list of the states 
of one or all of the installed tasks in the system, 
depending on the presence of the taskname parameter. The 
format of the display is as follows: 


taskname tcbaddr parname pcbaddr taskaddrlimits pri defpri 
STATUS: statusflags 
TI - ddn: IOC - iocount EFLG - eventflags 


This display is in the same format as that of 
SHOW TASKS/ACTIVE/FULL. (See Section 3.76 for a description 
of the display.) 


taskname 


Specifies a task for which full information is to be 
displayed. If you do not specify a task name, information 
about all installed tasks is displayed. 
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3.78 SHOW TASK:taskname/DYNAMIC 


SHOW TASK: taskname/DYNAMIC displays a moving picture of a task’s 
activity on the terminal. 


Syntax 

SHOW TASK: taskname/DYNAMIC[ /qualifier] 
taskname 

Specifies the task you want to inspect. 
qualifier[s] 

Can be one or more of the following: 


/RATE:nN 
/PRIORITY:n 


Qualifiers 
/DYNAMIC 


Specifies that you want the moving display. Tis: tunction 
is performed by the RMD task. RMD has four display pages: 


® Task that displays a task header 
® Active that displays all or part of the Active Task List 
@ Memory that displays the contents of memory 


e Help that provides help on RMD 


Once you have invoked any one of these pages, through either 
a SHOW TASK/DYNAMIC command or a SHOW MEMORY command, you 
can move from one page to the other without leaving RMD. 
The first character of each page name is a command to RMD to 
gO. £0>that pages In-addition, a .<CPRL/(> “entered “from. a 
page permits you to enter setup commands for that page. See 
Chapter 8 for more information on the features of RMD. 


The setup commands for the Task page permit you to change 
the task header being displayed. The task you name remains 
the default display for the Task page. This means you can 
observe a single task header, then jump to the Memory page 
or the Active page, and then back to the Task page and the 
named task will still be on display. 
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PRAT EEN 


The /RATE qualifier allows you to set the rate at which the 
RMD display screen is to be replotted on the first display. 
The value n is the number of seconds between replots. The 
default nis 1. You can change the rate by pressing ESC and 
entering a new rate. The rate setting returns to 1 as_ soon 
as you change pages. If you want a slower rate, you must 
reset the rate each time you change the page. 


Use this qualifier to slow down the display. 


Task headers may change more often than once per second, but 
once per second is the most rapid rate available. 


/PRIORITY:n 


This qualifier specifies the highest priority to be 
displayed. The default: is 250; the Arghesc priority on: the 
system. Use this qualifier to shorten the display to one 
screen length. 


Notes 


Tasks built including ODT can be observed using this 
command, but if you are single-stepping through the task or 
otherwise using breakpoints, the registers displayed will be 
those of the ODT task, not those of the named task. 


This display is particularly useful for observing complex 
assemblies, as you can tell how far the assembly has gone by 
which files are open. You may also be interested in 
observing the Task Builder at work. 
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3.79 SHOW TASKS/ACTIVE/DYNAMIC 


SHOW TASKS/ACTIVE/DYNAMIC displays either a moving picture of the 
Active Task List on a video terminal, or a snapshot display on a 
hard-copy terminal. 
Syntax 

SHOW TASKS/ACTIVE/DYNAMIC[ /qualifier] 
qualifier 

/RATE:n 
Qualifiers 


/RATE:n 


The /RATE qualifier allows you to set the rate at which the 
RMD display screen is to be replotted on the first display. 


The value n is the number of seconds between replots. The 
default n is 1. You can change the rate once the display 
begins by pressing the ESC key and entering a new rate. The 
rate setting returns to 1 aS soon as you change pages. If 


you want a slower rate, you must reset the rate each time 
you change the page. 


Use this qualifier to slow down the display. 
The Active Task List may change more often than once _ per 


second, but once per second is the most rapid rate 
available. 
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3.80 SHOW TASK/LOGICAL UNITS 
SHOW TASK: taskname/LOGICAL_UNITS displays the static logical unit 
number (LUN) assignments for an installed task. 
Syntax 
SHOW TASK: taskname/LOGICAL UNITS 


taskname 


Specifies the task for which you want LUN assignments 


displayed. This must be the name of a task installed 
through INSTALL, and not through the install-run-remove form 
of RUN. 


The display consists of a list of physical devices and 
corresponding static LUN assignments. The display does not 
show any dynamic LUN assignments, even when the specified 
task is running. 

Prompts 


Taskname? taskname 
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3.81 SHOW TERMINAL 


SHOW TERMINAL displays information about your terminal and 
another optional terminal connected to the system. Each SHOW 
TERMINAL attribute is directly related to ae SET TERMINAL 


attribute (refer to Set Terminal for a discussion of these 
attributes). 
Syntax 
SHOW TERMINAL[:ttnnn:] [/attributes[s] ] 
tCtnnn 


Is the number of the terminal for display 
attribute 

Can be one or more of the following: 

Group i: Common Use 


/{NO]LOWERCASE /{NO]UPPERCASE 
/WIDTH:n 


Group 2: Terminal Setup 


/VT100 /NT101 
/VT102 /VNT105 
/NT125 /NT131 
AVES 2 /VT2Z2XX 
/LASO /ULA1L00 
Poe Oaks /LOQP02 
/PC300 /{NO]FORM_FEED 
/{NO]TAB /{NO]HARDCOPY 
/{NO]SCOPE /PAGE_LENGTH:n 


Group 3: Task Setup 
/{NO]ECHO /(NO]ESCAPE 


/{NO]TYPEAHEAD[ :n] /{NO]WRAP 
/{NO]EIGHT_BIT 


Prompts 


None 
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3.82 SPAWN 


The SPAWN command allows tasks to be executed in the background. 
These tasks allow you to continue to use the terminal. For 
example, SPAWN can initiate a task building session, allowing you 
to perform other tasks. 
SPAWN should not be used with tasks that attach the terminal. 
SPAWN will return an error message, if it was asked to initiate 
an uninstalled task. 
Syntax 

SPAWN cmd 
cmd 

Is any PRO/Tool Kit Command Language command. 


Prompts 


None 
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3.83 START 


START resumes the execution of a task that was halted by a STOPSS 
directive. Starting a task that has been stopped is different 
from continuing a suspended task. 
Syntax 

START taskname 
taskname 

Is the name of the task you want to start. 
Prompts 


Taskname? taskname 
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3.84 START/UNBLOCK 
This command continues the execution of a task that was 
by the STOP/BLOCK command. 
Syntax 

START/UNBLOCK taskname 
taskname 

Is the name of the task to be unblocked. 


Prompts 


Taskname? taskname 
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blocked 


STOP/BLOCK 


3.85 STOP/BLOCK 


This command blocks an installed, active task. After execution 
of this command, the task no longer executes or competes for 
memory (refer to START/UNBLOCK). 
Syntax 

STOP/BLOCK taskname 
taskname 

Is the name of the task to be blocked. 


Prompts 


Taskname? taskname 
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3.86 SUBMIT/REMOTE 


With PRO/DECnet only, SUBMIT/REMOTE directs an existing command 
File on a remote node to be executed. The file is queued to the 
remote node’s command file or batch file processor. If the 
command file is not on the node where it will be executed, you 
may want to use a COPY command with a /SUBMIT qualifier. 

The success of the command does not guarantee that the batch or 
command file was executed successfully, only that the execution 
request was given successfully to the remote processor. 

Syntax 


SUBMIT/REMOTE[/qualifier[,s]] commandfile[,s] 


qualifier 
Can. be one -or' more of the following: 


/ LOG 
/NOWARNINGS 


commandfile 
The output file descriptor for each remote node command file 
that you want to execute. Command files are not deleted 
after execution. 


Prompts 


File(s)? commandfile[,s] 


Qualifiers 
EOC 


Specifies that the names of files submitted are to _ be 
displayed as the operation is performed. 


/NOWARNINGS 


Specifies that the "No such file" error messages should not 
be displayed when the input files specified do not exist. 
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3.87 TYPE 


This command displays the contents of a file or group of files on 
the terminal. 


Syntax 
TYPE[/qualifier[{s]] filespec[,s] 
qualifier 
Can be one or more of the following: 
/DATE:dd-mmm-yy 
/SINCE:dd-mmm-yy 
/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/ TODAY 
/EXCLUDE: filespec 
/NOWARNINGS 
/ SHARED 


With PRO/DECnet DCL extensions, the following qualifiers are also 
available: 


/LOG 

/MACY11 
filespec 

Is the name of the file to be displayed. 
Prompts 

File(s)? filespec[,s] 
Qualifiers 


/DATE:dd-mmm-yy 


The /DATE qualifier specifies that you want the TYPE command 
to affect only files created by the value specified for 
/DATE. 
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/SINCE:dd-mmm-yy 


The /SINCE qualifier specifies that you want the TYPE 
command to affect only files created on or since the value 
specified by /SINCE. 


/THROUGH: dd-mmm-ryy 


The /THROUGH qualifier specifies that you want the TYPE 
command to affect only files created on or before the value 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers can be combined to 
specify that you want the TYPE command to affect only files 
created within that range. 


/ TODAY 


The /TODAY qualifier specifies that you want the TYPE 
command to affect only files created on the same day as the 
command is issued. 


/EXCLUDE: filespec 
The /EXCLUDE qualifier specifies that you want the TYPE 
command not to affect certain files. The filespec argument 
to /EXCLUDE can contain wildcards, but the filespec must 
contain a version number, either explicitly or as the "*" 
wildcard. 


/NOWARNINGS 


Specifies that the "No such file" error messages should not 
be displayed when the input files specified do not exist. 


/ SHARED 
Specifies that other users are able to access the file while 
you are typing it. 

Additional Qualifiers Available with PRO/DECnet 

Command Qualifiers 


/ LOG 


Specifies that the names of files typed and their sizes are 
to be displayed as the operation is performed. 
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File Qualifiers 
/MACY11 


Specifies that the input or output file on the _ remote 
TOPS-10 or fTOPS-20 system is in MACY11 format. This 
qualifier is used to inform the remote DECsystem to handle 
the file appropriately when copying to or from the P/OS 
system. /MACY11 must be entered after the file 
specification in the command line. 
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3.88 UNLOAD 


The UNLOAD command removes a loadable device driver from memory. 
Note that the device driver data base will not be removed from 
the system. Reboot the system to remove the driver data 
Structures. 

Note the following restrictions: 


o If a device is mounted, attached, or has outstanding I/O, its 
driver cannot be unloaded. 


o The UNLOAD command cannot remove a data base from memory, 
even if the data base was loaded by means of the LOAD 
command. 

Syntax 


UNLOAD dd: 


ad: 
Is a two-character ASCII device name. 


Prompt 


Device? dd: 
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3.89 UNLOCK 


UNLOCK unlocks locked files. Locked files are files that have 
been improperly closed because a task aborted or _ stopped 
execution while the file was open. Locked files are identified 
by an L in the directory listing. 


Syntax 

UNLOCK[ /qualifier[s]] filespec[,s] 
qualifier 

Can be one or more of the following: 


/DATE:dd-mmm-yy 

/SINCE:dd-mmm-yy 

/THROUGH: dd-mmm-yy 
/SINCE:dd-mmm-yy/THROUGH: dd-mmm-yy 
/TODAY 

/EXCLUDE: filespec 

/{NO]WARNINGS 


filespec 
Is the name of the file to be unlocked. 
Prompts 
File(s)? Cilespec[,s] 
Qualifiers 
/DATE:dd-mmm-yy 
The /DATE qualifier specifies that you want the UNLOCK 
command to affect only files created by the value specified 


for /DATE. 


/SINCE:dd-mmm-yy 
The /SINCE qualifier specifies that you want the UNLOCK 
command to affect only files created on or since the value 
specified by /SINCE. 


/THROUGH: dd-mmm-yy 
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The /THROUGH qualifier specifies that 
command to affect only files created 
specified by /THROUGH. 


/SINCE: dd-mmm-yy/THROUGH: dd-mmm-yy 


The /SINCE and /THROUGH qualifiers 
specify that you want the UNLOCK 
files created within that range. 


/ TODAY 


The /TODAY qualifier specifies that 
command to affect only files created 
command is issued. 


/EXCLUDE: filespec 


The /EXCLUDE qualifier specifies that 
command not to affect certain files. 
to /EXCLUDE can contain wildcards, 
contain a version number, 
wildcard. 


/{NO]WARNINGS 
The /[NO]WARNINGS qualifier 


file" 
files specified do not exist. 
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but 
either explicitly or as the "*" 


specifies 
error messages should not be displayed when the input 


you want the UNLOCK 
on or before the value 


can be combined to 
command to’ affect only 


you want the UNLOCK 
on the same day as the 


you want the UNLOCK 
The filespec argument 
the filespec must 


that the "No such 


CHAPTER 4 
THE INDIRECT COMMAND PROCESSOR 


This chapter describes the Indirect Command Processor 
("Indirect") and indirect command files. Section 4.33 through 
4.54 describe the processor directives that control execution of 
indirect. The final two sections in the chapter provide 


information on compatibility with RSX systems, as well as errors 
that Indirect can return. 


4.1 INDIRECT COMMAND FILES 


An indirect DCL command file is a text file containing a list of 
DCL-specific command lines and special directives that allow you 
to control command file processing. The indirect command 
processor reads the indirect DCL command file, interprets the 
directives, and passes the DCL commands to DCL. 


To initiate an indirect DCL command file, enter the file 
specification, preceded by an at sign (@), whenever DCL can 
accept input. For example: 


S$ @DCLIPT.CMD 
The default file type for indirect DCL command files 1s _ .CMD. 
Thus, the command line in the previous example could also be 
input as follows: 


S @DCLIPT 


Indirect DCL command files can also be nested. The maximum level 
of nesting is four. 


Note that the Indirect directives described in this chapter can 
only be used in indirect DCL command files. 


INDIRECT COMMAND PROCESSOR 


4.2 INDIRECT COMMAND PROCESSOR 

When processing an indirect command file, the Indirect task first 
reads the command file and interprets each command line either as 
a command to be passed directly to DCL or as a request for action 
by Indirect. The directives to Indirect are distinguished by a 
period (.) as the first character in the line. 


The Indirect directives form a procedural language that allows 
you to: 


@ Define and assign values to logical, numeric, and string 
symbols 


® Substitute a symbol’s value into any line of the command file 
e Perform arithmetic functions 

@ Manipulate strings 

@ Display text on the user’s terminal screen 

@ Ask questions of a user 

@ Control the flow of a command file 

e Call subroutines 

@e Detect error conditions 

6 Test symbols and conditions 

® Create and access data files 

® Parse commands and data 

© Enable or disable any of several operating modes 


@® Display forms and control user entry of data 


Two directives (.BEGIN and .END) permit you to use block 
structure in the command file. Modular, block-structured command 
files are easier to debug and maintain. More importantly, 


Begin-End blocks isolate local symbol definitions as well as 
labels, and thus conserve symbol table space. 


When you define a symbol, Indirect creates an entry for the 
definition in an internal symbol table. These symbol table 
entries retain their definitions throughout execution of the 
command file if defined locally, or throughout the execution of 
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all levels of nested command files if defined globally. Local 
symbols defined within a block, however, retain their definitions 
only throughout the execution of the commands within that block; 
they are erased from the symbol table when Indirect encounters an 
.END directive. 


An Indirect directive (.ENABLE GLOBAL) allows the definition of 
some symbols as global to all file levels. Otherwise, each time 
Indirect enters a deeper level, it masks all symbols defined by 
the previous level out of the symbol table so that only symbols 
defined in the current level are available. These symbols are 
local only to the level of the file in which they are defined. 
When control returns to a previous level, the symbols defined in 
that level become available once again and the ones from the 
deeper level are lost. 


When Indirect reaches the end of the highest level indirect 
command file, it displays the following message (unless inhibited 
by the .DISABLE DISPLAY directive): 


S @<EOF> 
and then exits. DCL then prompts for a command from the 
keyboard. Indirect displays on the requesting terminal’s screen 


every DCL command line as it is executed. 


An Indirect file can also include comments, which the processor 
prints at the terminal screen. Comments that begin a line 
interpreted by DCL have a leading semicolon (;). Comments that 
appear after the start of a DCL command line have a leading 
exclamation point (!). All lines in an indirect command file 
that begin with a period in column 1 followed by a semicolon (.;) 
are treated as comments but are not displayed when the file is 
processed. 


Indirect attaches the terminal while processing contiguous 
comment lines that begin with a semicolon. This permits you to 
type CTRL/O and suppress a lengthy comment. Output is resumed by 
typing another CTRL/O or is resumed at the next DCL command line 
or Indirect directive statement in the command file. 
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If the specified command file cannot be found in the current 
directory, Indirect will attempt to translate the logical name 
INDSCOMMAND LIBRARY and look for the command file there. This 
permits a user to place commonly used command files in one place. 
The following DCL command establishes this behavior. 

S ASSIGN DW1:(USERLIBRY] INDSCOMMAND_ LIBRARY 
Subsequently, the user command: 


S @COMPILE 


results in Indirect first looking for COMPILE.CMD in the current 
derault directory and, if not. found, Looking for: 


DWL? (USERGLIBRY |}COMPILE.~CMD 


Note that the PRO/Tool Kit uses LB:[{1,2] as the initial value of 
INDSCOMMAND_LIBRARY. You can specify your own initial value in 
the. file START .CMD. 


4.3 SUMMARY OF INDIRECT DIRECTIVES 


The Indirect directives described in this chapter are listed here 
by category. 


Label Definition 


Label: Assigns a name to a line in the command 
file so that the line may be referenced. 


Symbol Definition 


.ASK Defines or redefines a logical symbol and 
assigns the symbol a true or false value. 


.ASKN Defines or redefines a numeric symbol and 
assigns the symbol a numeric value. 


-ASKS Defines or redefines a string symbol and 
asSigns the symbol a character string 
value. 


. ERASE 


-DE Py sob) 


,ooLN 


“Ob. D/ soe lO 


po eG 


Kom o 


. TRANSLATE 


File Access 


.DATA 


CHAIN 


. CLOSE 


OPEN 


~OPENA 


.OPENR 


. PARSE 
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Deletes all local or global symbol 
definitions or a single global symbol 
definition. 


Defines or redefines a logical symbol and 
assigns the symbol a true cr false value. 


Defines or redefines a numeric symbol and 
assigns the symbol a numeric value. 


Redefines the radix of a numeric symbol. 


Defines or redefines a logical symbol and 
assigns the symbol a true or false value. 


Defines or redefines a string symbol and 
assigns the symbol a character string 
value. 


Attempts to translate a logical name and 
return its equivalence value. 


Specifies a single line of data to output 
to a file. 


Closes the current indirect file and uses 
commands from another file. 


Closes a file. 
Creates and opens an output data file (if 


the file exists, creates a new version and 
opens it). 


Opens an existing file and appends 
subsequent data (does not create a new 
version). Defaults to .OPEN if the file 


does not exist. 


Opens a file for reading with the .READ 
directive. 


Parses strings into substrings. 


- READ 


Logical Control 
» BEGIN 
. END 


BALE 


. GOSUB 


sGOTO 


~ONERR 


.RETURN 


zo .OP 


Logical Tests 


aL 


.IFACT/.IFNACT 


PDE 7. PN DE 
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Reads a record from ae file into a 
specified string variable. 


Marks the beginning of a Begin-End block. 
Marks the end of a Begin-End block. 


Terminates processing of either Indirect 


or the current command file, returns 
control to the invoking terminal or to the 
previous level, and Optionally sets 


Special symbol <EXSTAT> value. 


Calls a subroutine within the command 
file. 


Branches to a label within the command 
file. i 


Defines logical end-of-file. Terminates 
file processing and exits. This directive 
1S equivalent to Lhe «STOP directive. 


Branches to a label upon detecting a 
specific Indirect error condition. 


Effects an exit from a subroutine and 
returns to the line immediately following 
the subroutine call. 


Terminates indirect command file 
processing and optionally sets Indirect 
exit status. This directive is equivalent 
to the logical end-of-file (/) directive. 


Determines whether or not a symbol 
satisfies a condition. 


Determines whether or not ae task 1s 
active. 


Determines whether or not a symbol is 
defined. 


. IFENABLED/ 

. IFDISABLED 
.IFINS/.IFNINS 
. IFLOA/.IFNLOA 
.IFT/.IFF 
.TEST 


- TESTDEVICE 


-TESTFILE 


.- TESTPARTITION 


-TESTSYSTEM 
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Tests the .ENABLE/.DISABLE options. 


Determines whether or not aetask is 
installed in the system. 


Determines whether or not a device driver 
is loaded. 


Determines whether a logical symbol is 
true or false. 


Tests the length of a string symbol or 
locates a substring. 


Returns information about a device in the 
system. 


Determines if a specified file exists and 
determines the physical device associated 
with a logical device name (performs 
device translation). 


Returns information about a partition in 
the system. 


Returns information about the presence of 
certain operating system features. 


Enable or Disable an Operating Mode 


. ENABLE/.DISABLE 


Enables or disables control of the 
following modes: 


substitution 

timeout parameter 
lowercase 

terminal attachment 
data 

global symbol 

symbol radix 

command line echo 
command display 

field display 

command passing to DCL 
file deletion 

truncate error suppression 
escape 

CTRL 2 <exwe 

overflow 
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Increment or Decrement Numeric Symbols 


SL NC Adds one to a numeric symbol’s value. 
.DEC Subtracts one from a numeric  symbol’s 
value. 


Execution Control 


. DELAY Delays the execution of an indirect 
command file for a specified period of 
time. 

. PAUSE iS a nOo=0p under the . PRO/VTOoOL ‘Kits 1 


does not suspend execution of Indirect. 


.WAIT Is a no-op under the PRO/Tool Kit. It has 
no effect. 


.XQT Is a no-op under the PRO/Tool Kit. ‘fee 
passes the DCL command line to DCL. 
Indirect does not proceed until that 


command is complete. 


Special Purpose 


. FORM Provides access to the PRO/FMS form 
driver, allowing FMS commands to be passed 
CO. FMS* 


4.4 SYMBOLS 


The Indirect Command Processor enables you to define symbols. 
These symbols can then be tested or compared to control flow 
through the indirect command file. They may also be substituted 
in DCL commands, data records for data files, or comments to be 
displayed on the screen. 


Symbol names are ASCII strings from one through six characters in 
length. They must start with a letter (A through Z) or a dollar 


Sign ($). The remaining characters must be alphanumeric or a 
dollar sign. 


There are three symbol types: 


Oo. bogical 


SYMBOLS 


© Numeric 

9 String 
A logical symbol has either a true or false value. 
A numeric symbol can have a numeric value in the range of 0 
through 65535 (decimal). The symbol can be defined to have 
either a decimal or octal radix. The radix is relevant only when 


the symbol is substituted. 


A string symbol has as its value a string of ASCII characters, 
with a length of 0 through 132 (decimal) characters. 


A symbol’s type (logical, numeric, or string) is defined by the 
first assignment directive that assigns a value to the symbol. 


Assignment directives can assign: 


@ A true or false value to define a logical symbol (defined by 
.ASK, .SETL, .SETT, or .SETF). 


® An octal or decimal number to define a numeric. symbol 
(defined by .ASKN, .SETN, .SETO, or .SETD). 


@ A character string to define a string symbol (defined by 
sAoKo.: «READ. -OT- £<SETS').. 


4.4.1 Special Symbols 


Indirect automatically defines special symbols dependent upon 
specific system characteristics and the replies to queries 


presented during command file execution. As with symbols, 
special symbols can be compared, tested, or substituted and 
consist of three types: logical, numeric, and string. All 


special symbols have a common format--angle brackets (<>) enclose 
the special symbol name. 


4.4.1.1 Special Logical Symbols - The special logical symbols 
are assigned a true or false value under the following 
circumstances: 
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Symbol 


<ALPHAN> 


<DEFAUL> 


<EOF> 


<ERSEEN> 


<ESCAPE> 


<FALSE> 


<NUMBER> 


SYMBOLS 


Value 


Set to true if last string entered in response 
to an .ASKS directive or tested with a .TEST 
directive contains only alphanumeric characters. 
An empty string also sets <ALPHAN> to true. 


Set to true if answer to last query was 
defaulted (the <RETURN> key was pressed once) or 
a timeout occurred. 

Set to true if the last .READ or .ASKx directive 
resulted in reading past the end of the file. 
Otherwise, <EOF> is set to false. 


Set to true if any of the following conditions 
are true. 


@® <FILERR> is less than 0, if a negative error 
code was returned 


@ If an exit status <EXSTAT> value worse than 
<WARNING> was returned 


@ <EOF> is set to true 
@ If you used the command line .SETT <ERSEEN> 


The command line -SETF <ERSEEN> sets the 
following conditions: 


@ <FILERR> is set to 0 
® <EXSTAT> is set to 0 
® <EOF> is set to false 


Set to true if last question was answered with 
an ALTmode or ESCape. Otherwise, <ESCAPE> 15s 
set to false. 


Logical constant used for comparisons with the 
.IF directive or as a default for the .ASK 
directive. 


Set to true if the last string entered in 
response to an .ASKS directive or tested with a 


. Teor directive contains only numeric 
characters. An empty string also sets <NUMBER> 
LO: so Pues: 
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<OCTAL> set to true if the answer to the last .ASKN 
directive or the radix of the numeric symbol 
tested in the last .TEST directive is octal or 
if the last string tested with a .TEST directive 
contained all numeric characters in the range 0 
through: 7. 


<PRIVIL> Set to true if the current user is privileged. 
Its value is derived from the flag contained in 
the terminal data base. The flag iS set when 
IND executes. 


<RAD50> Set to true if last string entered in response 
to an .ASKS directive or tested with a .TEST 
directive contains only Radix-50 characters. 


Radix-50 characters are the uppercase 
alphanumeric characters plus period (.) and 
adgitar “sign. (3) A blank is not a Radix-50 


Character in this context. An empty String also 
sets <RAD50> true. 


<TIMOUT> Set to true if timeout mode is enabled and the 
last .ASKx directive timed out waiting for a 
user response. 


<TRUE> Logical constant used for comparisons with the 
.IF directive or as a default for the .ASK 
directive. 


4.4.1.2 Special Numeric Symbols - The special numeric symbols 
are assigned the following values: 


Symbol Value 


<ERRCTL> Controls the way in which Indirect processes 
errors. The symbol is treated as an 8-bit mask. 
For each class of error that a user’s .ONERR 
target routine processes, the appropriate bit is 
set in the mask. If the bit is clear, Indirect 
exits after printing the error information. See 
Section 4.34 for details on .ONERR. 


<ERRNUM> 


<ERRSEV> 


<EXSTAT> 


<FILERR> 
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It the eighth bit, the sign bit or 200 (octal), 
1S set, Indirect does not print any information 
about the error. 


The initial default value for <ERRCTL> is 1, 
which implies that only class 1 errors can be 
handled with an .ONERR address, and that error 
messages will be printed. Note that if you 
attempt to trap errors other than default class 
1, processing cannot continue in most cases. 
The error service routine is limited to a _ fatal 
error message and .EXIT. The internal state of 
Indirect is indeterminate in all but class 1 
error cases 


See Section 4.56.2 for a list of error messages 
and their asigned values. 


Assigned the class number of an error that 
Indirect has finished processing. This value 
can be used for processing specific error types 
with an .ONERR routine. 


Assigned the error severity mask associated with 
the error that Indirect has finished processing. 
This bit mask corresponds to the bit mask 
<ERRCTL> used to control the processing. 


Assigned a numeric value depending upon the 
status of the last DCL command executed. User 
programs can generate any 16-bit value as an 
exit status. Most DIGITAL-supplied programs, 
however, exit with one of the following status 
values: 


Value 


Q Warning 

1 Success 

2 ECror 

4 Severe Error 


Assigned the FCS-11 or 170 -driver status ‘code 
resulting £rom <a <«FTESTPILE,. «<OPENX,).°Or «<READ 
directive operation. See Appendix B for a 
description of the codes. 


<FILER2> 


<FORATT> 


<MEMSIZ> 


<SPACE> 


<STRLEN> 


<OrM TYPO 


<SYSTEM> 


<SYUNIT> 


<TLCELPRP> 


<TICWID> 


<TISPED> 
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Assigned the second error code word that is 
returned by the FMS-related .FORM command. 


Assigned the octal value of the file attributes 
that were used to open the data files. 


Assigned the value of the current system memory 
size in K words (K is 1024.). 


Assigned the number, in octal, of free bytes in 
the internal symbol table for Indirect. The 
number does not reflect the amount of space that 
could be gained by the automatic extension of 
the Indirect task. 


Assigned the length of the string entered in 
response to the last .ASKS directive or the 
string tested by the last .TEST directive. 


Assigned the numeric code for the type of symbol 
tested with a .TEST directive. The symbol types 
have the following code numbers: 


String - 4 
Numeric - 2 
Logical - Q 
Assigned an octal number to represent the 


operating system on which Indirect 1s running. 
The value 11 is for the P/OS system. 


Assigned the unit number of the user’s default 
device (SY:). 


Assigned the current page length setting for the 
screen. 


Assigned the current page width setting for the 
screen. 


Assigned the baud rate Low transmitting 
characters from the host system to the terminal. 
Indirect attemtps to determine the baud rate 
when you first invoke it. This information 1s 
useful for determining the quality and quantity 
of information to be transmitted. The following 
list gives the octal value that corresponds to 
each baud rate. 


<TITYPE>S 
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Symbol 


<ACCOUN> 
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Octal Value Baud Octal Value Baud 
1 or: 0D 0 13 1200 
2 50 14 1800 
3 75 je) 2000 
4 100 16 2400 
5 EO 17 3600 
6 134 20 4800 
7 150 21. 7200 

LG 200 22 9600 

Gen 300 23 EXTA 

12 600 24 EXTB 


Assigned the terminal type of the terminal from 
which Indirect: 12S running. The Professional 
terminal type is 35. 


Special String Symbols - The special string symbols 

assigned the following string values. 

Value 

(RSX-11M-PLUS and P/OS systems only.) Assigned 

certain accounting information from ai user’s 

accounting block (UAB). The information is in 

the following format (note the trailing comma): 

unam,sessid,accnum,cpu,dir,gio,tas,atsks 

unam The first 14 characters of the user 


mame aS it appears in the system 
account file. 


sessid Session ID, null on P/OS. 

accnum Account number, null. on P/0Ss:. 

epu CPU ticks used since login, null on 
P/OS. 

air Number of system directives issued 


Since: login, mult. -on 270s. 


GLO Number of QIO directives issued since 
login; null on P7Os. 


tas Number of tasks run since login, null 
on P/OS. 
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ale 


<CLI> 


<DATE> 


<DIRECT> 


<EXSTRI>D 


<FILATR> 


<FILSPC> 


<LOGDEV> 


<LOGUIC> 


<NETNOD> 
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atsks Number of active tasks, null on P/OS 


Assigned the acronym (3 through 6 letters) of 
the current command line interpreter. This 
symbol is fixed at "DCL" under the PRO/Tool Kit. 


Assigned the current date. The date format is 
dd-mmm-yy. 


Assigned the name of the current default 
directory; the format is [ddddddddd]}. 


Contains the string results from a more deeply 
nested indirect command file. The results are 
sent to the calling command file. Cleared after 
each DCL command. 


Assigned the seven words of file attribute 
information contained in the FCS-11 File 
Descriptor Block (FDB). 


Assigned the fully-qualified specification for 
the file referred to with the last .OPEN, 
.OPENA, .OPENR, or sTEOTE LEE directive 
operation, or in the last specification for a 
nested command file. 


Assigned the device name and unit number of the 
user’s login account on multiuser protection 
systems. On other systems, <LOGDEV> is assigned 
SYO0: at the time IND is invoked. 


Assigned the login UIC of the current user on 
multiuser protection systems; the format is 
[ggg,mmm]. On other systems, <LOGUIC> is 
assigned the current default UIC. 


Assigned the DECnet node name of the system. If 
the asystem is not on the DECnet’ system, 
<NETNOD> is assigned the string PRO. 
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<SYSDEV> Assigned the physical name for the boot device 
for the system. The device name is in the form 
ddn. 

<SYDISK> Assigned the device mnemonic (two letters) of 
the user’s default device (SY:); format is dd. 

<S io. D> Assigned the operating system’s baselevel 
number. 

<TIME> Assigned the current time; format is hh:mm:ss. 

<UTC> Assigned to default UIC. 


4.4.2 Numeric Symbols and Expressions 


A numeric symbol is a string of digits representing a value in 
the range of 0 through 177777 (octal) (0 through 65535 decimal if 
immediately followed by a period or if decimal mode has_ been 
enabled). If an arithmetic operation yields a result outside of 
this range, a fatal error occurs and the following message is 
displayed: 


IND =- NUMERIC UNDER- OR OVERFLOW 


A numeric symbol or constant may be combined with another numeric 
symbol or constant by a logical or arithmetic operator to form a 
numeric expression. Arithmetic operators are used to add (+), 
Subtract. (=), Multiply: -(*), and. divide (7). <Gbegical operators 
are the inclusive OR (!), logical AND (&), and NOT (#). No 
embedded blanks or tabs are permitted between operators. 


Numeric expressions are evaluated from left to right unless 
parentheses are used to form subexpressions that are evaluated 
first. For example, the directive lines: 


.SBTN Ni 2 
.SETN N2 3 
-SETN N3 N14+N2*4 


assign numeric symbol N3 the value 24 (octal), whereas’ the 
following directive lines assign numeric symbol N3 the value 16 
(octal): 


.SETN N1 2 
.SETN N2 3 
.SETN N3 N1+(N2*4) 
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Numeric expressions are permitted as second operands in numeric 
-IF and .SETN directives. They are also permitted as range and 
default arguments in .ASKN and .ASKS directives. The directives 
-EXIT and .STOP permit numeric expressions to represent exit 
status. 


With each numeric symbol, Indirect associates a radix -- either 
octal or -decimal. The radix of a numeric symbol changes each 
time the symbol is assigned a new value. If you use a numeric 
expression to asSign a new value to a symbol and all operands in 
the expression are octal, then the symbol is set to octal. Lt 
any operand in the expression is decimal, the symbol is set to 
decimal. For example: 


-SETN N2 3. 

.SETN N3 Ni+3 
.SETN N3 N1+3. 
.SETN N3 N1+N2 


N2 1s decimal 
N3 is octal 

N3 is decimal 
N3 is decimal 


e—_ eum o—=— ¢=a 


You can also assign a new value to a symbol with the .ASKN 
directive. 


The .SETO and .SETD directives allow you to change the radix of a 
numeric symbol without changing the value of the symbol. For 
example: 


SSETM ONT: 20: ! Ni 
.SETO Ni ! Ni 


il 


10 decimal 
12 octal 


it 


The radix of a numeric symbol does not affect arithmetic 


operations or comparisons. The radix is important only when 
substituting a numeric symbol into a string. If the radix of the 
symbol is octal, the value of the symbol is substituted into the 
string as an octal number. If the radix is decimal, the value 1s 
substituted as a decimal number. For example: 

-SEIN Ni 20. ! Ni = 10 decimal 

; N1 = ‘N11’ ! Displayed as ; Ni = 10 

.SETO N1 ! Make N1 octal 

; NI = ‘N11’ ! Displayed as ; Ni = 12 


If you substitute a numeric symbol into a string and_ the 


substituted number is decimal, a period (.) following the symbol 
mame causes a trailing period to be included in the = string 
(following the substituted number). For example: 

.SETN Ni 10. Ni = 10 decimal 


1 
> Nl = ‘'N1.’ ! Displayed as ; Ni = 10. 
sSETO Ni ' Make Ni octal 
BN ee ND ! Displayed as ; Nl = 12 


SYMBOLS 


You can also force a numeric symbol to be substituted as an octal 
or decimal number by using a substitution format control string. 
For example: 


“SETN: Ni 220); ! N1 = 10 decimal 
> Ni = 'N1ISD" ! Displayed as ; Ni = 10 
; Ni = 'N1%30’ ! Displayed as ; Ni = 12 


4.4.3 String Symbols, Substrings, and Expressions 


A string constant is a string of any printable characters 


enclosed by quotation marks. Empty strings are also permitted. 
The number of characters cannot exceed 132 (decimal). For 
example: 

"ABCDEF" 
String symbols may have the value of any string constant. The 


value is assigned by a .SETS or .ASKS directive. For example, 
the directive statements: 


~ oETS op) "ABCDEF" 
.OoEES S2 Si 


assign string symbol S2 the value of string symbol Si (that is, 
ABCDEF). 


A substring facilitates the extraction of a segment from the 
value of a string symbol. You can use substrings only in second 
operands of .SETS and .IF directives. For example, the directive 
statements: 


soe So Si "ABCDEF" 
SETS SZ Stiles] 


assign string symbol S2 the value of string symbol S1 beginning 
at character one and ending at character three (that is, ABC). 


You can also use the syntax [n:*] to extract the characters from 
position n to the end of the string. For example, the directive 
statements: 


.SETS S1 "ABCDEF" 
.SETS S2 S1[3:*] 


assign string symbol S2 the value "CDEF". 


SYMBOLS 


You can combine a string constant, symbol, or substring with 
another string constant, symbol, or substring by the string 
concatenation operator (+) to form a string expression. 


String expressions are permitted as second operands in .SETS and 
-IF directives where the first operand is a string symbol. For 
example, the directive statements: 


.SETS Sl "A" 
.SETS S2. "CDEF" 
“SETS SS ‘Sie"BYes2( 1434 


assign string symbol S3 the value of the concatenation of String 
symbol S1, string constant "B", and the first three characters of 
String symbol S2 (that is, ABCDE). 


4.4.4 Reserved Symbols 


Parameters for a command file can be passed to Indirect for 
processing. The parameters are stored in the following reserved 
local symbols: 


PQ, Pl, P2, P3, P4, P5, P6, P7, P8, P9, COMMAN 


The symbol COMMAN contains everything in the issuing command 
line, including the specification for the command file itself. 
The symbols PO through P9 contain individual elements of the 
command line. The elements are delimited by spaces. 


With the .GOSUB directive any parameters to the right of the 
label and to the left of a comment are transferred to the symbol 
COMMAN. The value of COMMAN can then be parsed to obtain formal 
call parameters. 


4.4.5 Symbol Value Substitution 


Substitution can occur in any command line. Indirect can use the 
values assigned to logical, numeric, string, or special symbols 
by replacing a normal parameter (for example, a device unit) with 
the symbol name enclosed in apostrophes (for example, 'DEV’). 
When a previous directive has enabled substitution mode (.ENABLE 
SUBSTITUTION), Indirect replaces the symbol name enclosed in 
apostrophes with the value assigned to the symbol. 


When Indirect encounters an apostrophe, it treats the subsequent 


text, up to a second apostrophe, as a symbol name. Indirect then 
searches the table of symbols for the corresponding symbol and 
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substitutes the value of the symbol in place of the symbol name 
and surrounding apostrophes in the command line. 


For example, the first three lines in the following example 
appear in an indirect command file. When the processor executes 
these lines, it displays the last two lines at the entering 
terminal’s screen. | 


-ASKS DEV MOUNT ON DEVICE? 
-ENABLE SUBSTITUTION 
MOUNT ‘DEV’ 


S * MOUNT ON DEVICE? [S]: D22: 
S MOUNT D2Z2: 


DZ2: was entered in response to the displayed question. This 
reply assigned the string value DZ2: to string symbol DEV. Then 
when Indirect read: 


MOUNT ‘DEV’ 
it substituted for 'DEV’ the value assigned to DEV (that is, 
Daze); If substitution mode was not enabled, Indirect would 


Simply have passed the line to DCL as it appeared in the command 
file (that is, MOUNT ’'DEV’). 


If substitution mode is enabled (it is enabled by default, if you 


have not disabled it), an apostrophe signals the beginning of a 
string symbol. Thus, to include a single quote as text within a 
command line (rather than as the start of a symbol), you must 


replace the single quote with two contiguous apostrophes ('’). 


If substitution mode is enabled, Indirect displays the following 
command file line: 


f DON‘’!T SHOOT 
as 


f DON’T SHOOT 


4.4.5.1 Substitution Format Control - The conversion of numeric 
values to strings and the placement of string and logical values 
in a substitution operation can be controlled with a format 
control string. The control string is in the following form: 


cae SYMDOL [COU ErPOLSENINgG 4.5 


SYMBOLS 


The control string begins with the percent sign (%) and ends with 
the second of the two apostrophes that denote the substitution 
operation. The control string consists of one or more of the 
following characters: 


C Compress leading, embedded, and trailing blanks, and 
remove embedded nulls. 

D Force the conversion of a numeric symbol to decimal. 

O Force the conversion of a numeric symbol to octal. 

S Perform signed conversion for a numeric symbol. 

M Perform magnitude conversion for a numeric symbol. 

Z Return leading zeros for a positive numeric value. 


Rn Righnt-7ustity the resulting string, truncating to ‘'n’ 
decimal characters if necessary. 


Ln Left-justify the resulting string, truncating to ‘'‘n’ 
decimal characters if necessary. 


Xx Convert the variable to Radix-50 characters. 


V If the symbol being substituted is numeric, convert the 
low byte to its equivalent ASCII character and 
substitute it. 


If the symbol being substituted is a string, convert 
the first character to its octal representation and 
substitute it. 
Indirect does not perform a consistency check on the control 
string. Tt ‘You specify conflicting: tormat characters, Indirect 
uses the last one specified. 


4.5 SWITCHES 
The indirect command processor accepts five switches: /TR, /DE, 
JCUl. JLB, and. /L0- 


Switch Function 


/{NO]JTR Displays a trace of the indirect command file on_ the 
screen. Thas. function 16 <weeful for Gdepugging an 
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/(NO]DE 


J{NOVCLI 


/LB 


SWITCHES 


indirect command file. Each command line, including 
Indirect directive statements, is displayed. The 
default is /NOTR. 


Indicates that the indirect command file is to be 
deleted when itsS processing is complete unless a 


logical end-of-file (/) or . STOP directive 1s 
encountered before the end of the file. The default is 
/ NODE. 

Passes commands not processed by Indirect to DCL. The 


default is /CLI. 


Indicates that the specified file is a universal 
library of command procedures and that the specified 
module is the procedure to be executed. 


When command procedures, which are indirect command 
files, are inserted into a universal library with the 
Librarian command, you can subsequently reference them 
with /LB:module. 


Command libraries are built by creating a universal 
library and inserting command files into it. You can 
then reference the procedures in the library with the 
following command line: 


@command-library/LB:module 
The default file type for a command library is .CLB. 


If you do not specify a module (@command-library/1lb), 
Indirect attempts to locate a module called .MAIN.. 


See the example below. 


The command file PARAM.CMD contains parameter 
definitions for the .SETN directive and the command 
file SYSPRC.CMD contains system-specific procedures. 
Use the following command lines to create the command 
library and enter the command files into it: 


R/CREATE/UNIVERSAL SYSTART.CLB 
R/INSERT SYSTART.CLB PARAM.CMD 
RYINSERE “SYS TART eC LB PROCED CMD 


Kr 
WwW Ww 


You can then use the following command lines to 
reference the command library modules: 


@SYSTART/LB: PARAM [Derine global symbol 
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@SYSTART/LB:PROCED !Run init procedure 


DIGITAL supplies a library of command procedures. The 
library is LB:[1,2]JINDSYS.CLB and it contains’ the 
following procedures: 

INDCFG Displays the current build parameters for the 
running Indirect task. 
@LB:{1,2]INDSYS/LB: INDCFG 

INDDMP Dumps to the screen the contents of the 
Indirect symbol table. 

@LB:[1,2]INDSYS/LB: INDDMP/LO 

INDPRF A sample procedure to fully parse file-name 
strings. 

To return a parsed string in <EXSTRI>: 
@LB:[1,2]INDSYS/LB:INDPRF DWi:[DATA]st.dat;2 

INDSFN Returns system configuration information. 

To return in <EXSTRI> whether the Floating 
Point unit is present: 
@LBi [1,2 )INDSYS/LBTINDSEN FPP 

INDVFY Displays the values of all of the special 
symbols. 
@LB:[1,2]INDSYS/LB: INDVFY 

QIOERR Returns a string expansion of the <FILERR> 
error codes. 
To returns in <EXSTRI> a string expansion for 
the code. 
@LB:[1,2]INDSYS/LB:QIOERR -33. 

FMSDEM Demonstrates the PRO/FMS interface 


incorporated into Indirect. 


See the description of the .FORM command. 


SWITCHES 


.MAIN Demonstrates how to use the command library. 
@LB:[{1,2]INDSYS/LB 


. INDEX Displays an index of the procedures in the 
Library « 


@LB:[{1,2]INDSYS/LB: . INDEX 
The following command line shows the format 
for invoking a command procedure in the 
library: 
@LB:[{1,2]INDSYS/LB: procedurename 

/{NO]LO Indicates that when a new command file is executing, it 


can have access to the local symbols created by its 
calling command file. The default is /NOLO. 


4.6 USING INDIRECT DIRECTIVES 
Directives must be separated from their arguments and from 
DCL-specific commands by at least one space. Only one directive 


per command line is allowed. 


You can insert any number of blanks and horizontal tabs in three 
places of a command line: 


@ At the start of the command line 
e Immediately following the colon (:) of a label 
@ At the end of the command line 
This allows you to format the command files for readability. The 


recommended procedure is to begin labels in column one and 
everything else in column nine (after one horizontal tab). 


USING INDIRECT DIRECTIVES 


An important exception is the lines processed between .ENABLE and 
-DISABLE DATA directives; no blanks or tabs are removed from 
these lines. For example: 


chit Z eGOTo.: 20 
MACRO/NOLIST TEST 
aU LINK TEST 
-OPEN DATFIL 
~-DATA XXXXX 
-ENABLE DATA 
This is data 
that goes into 
the data file. 
-DISABLE DATA 
GOTO: ZU 


Note that the .DISABLE DATA statement must begin in column 1 or 
Indirect will place it in the data file. 


4.6.1 Logical Tests 

A number of .IF directives make tests; if the test is true, 
Indirect processes the remainder of the command line. Logical 
tests can be combined to form compound logical tests by using the 
-AND and .OR directives. 


An implied .AND is effected when more than one .IF appears on the 
same line without being separated by an .AND directive. 


When using .AND and .OR, the .AND directive takes precedence over 
the .OR directive, as shown in the following example: 


,LET A. OR «LP B «AND «fr? Cc «GOTO -D 
That is, Indirect reads the line as: 

cle) & OR €.TFYE B sAND .2LFT COC) «GOTO. D 
Examples follow: 

slET A& <AND- stir 2B .GOTO HELP 


If the logical symbol A is true and the logical symbol B is 
false, control passes to the line containing the label .HELP:. 


i.e ree GOTO HELP 


Same effect as the previous directive (.AND implied). 


USING INDIRECT DERECTIVES 


JLELT A> oOR LEE Be RUN: TESTER 


If the logical symbol A is true or if the logical symbol B is 
false, the RUN command is issued. 


The following sections describe all of the Indirect directives. 


/ ~ DEFINE LOGICAL END-OF-FILE 


4.7 / - DEFINE LOGICAL END-OF-FILE 


The logical end-of-file directive (/) terminates file processing 
and exits. The message 


S$ @ <EOF> 
is then displayed. 
Format 


ye 
is the first nonblank character ona line. 


You can use this directive at any location in the command file to 
quickly terminate file processing, but care should be taken to 
avoid an inadvertent exit. 


Example 


-ASK CONT DO YOU WISH TO CONTINUE 
cEPR CONT: GOTO: 2:00 


ye 
sc 00 


-ASK - ASK A QUESTION AND WAIT FOR A REPLY 


4.8 .ASK - ASK A QUESTION AND WAIT FOR A REPLY 


The .ASK directive prints a question on the screen, waits for a 
reply, and sets a specified logical symbol to the value of true 
or false, depending on the reply. If the symbol has not already 


been defined, Indirect makes an entry in the symbol table. Let 
the symbol has been defined, Indirect resets its value (true or 
false) in accordance with the reply. Indirect exits with a fatal 


error if the symbol was previously defined as a String or numeric 
symbol. 


Formats (brackets are required syntax) 


-ASK SSSSSS txt-strng 
-ASK [default:timeout] ssssss txt-strng 
.ASK [:timeout] ssssss txt-strng 


where: 


SSSSSS The 1- to 6-character symbol to be assigned a 
true or false value. 


txt-strng The question or prompt that Indirect displays. 


default The default response; used if the question is 
answered with an empty line (null) or if timeout 
occurs. The default can be <TRUE> or <FALSE> or 
another logical variable. 


timeout The timeout count. Indirect waits this long for 
a response, then applies the default answer. 
The format for timeout is nnu, where nn is the 
decimal number of time units to wait and u is T 
(ticks), S (seconds), M (minutes), or H (hours). 
The timeout count is used only if timeout mode 
is enabled (.ENABLE TIMEOUT). 


The entire .ASK statement must fit on one command line. 


Note: that: 2 you omit the-default value but “specify a tameour 
eount; the colon is ‘required for positional identification. 


When executing an .ASK directive, Indirect displays txt-strng 
prefixed by an asterisk and sutfixed with. “? [Y/N]: ". Indrrect 
recognizes five answers: 


-ASK - ASK A QUESTION AND WAIT FOR A REPLY 


bs Y<RET> 

Set symbol ssssss to true. 
2. N<RET> 

Set symbol ssssss to false. 
oe <RET> 


Set symbol to false or to user-specified default value. 
<RET> indicates the <RETURN> key. 


4. <ESC> 
Set symbol ssssss to true and set the special logical 
symbol <ESCAPE> to true only if escape recognition has 
been enabled. <ESC> indicates the <ESCAPE> key. 
NOTE 
If escape sequence recognition is not enabled, 
the <F11> key (ESC) functions as the escape key 


5. <CTRL/Z> 


If CONTROL-Z mode is enabled, set <EOF> to true and 
proceed, or else exit immediately. 


Example 
The directive statement: 
-ASK INSFOR DO YOU WANT TO INSTALL FORTRAN 
displays 
S$ * DO YOU WANT TO INSTALL FORTRAN? [Y/N]: 
on the screen. Symbol INSFOR will be set to true or false after 


you type Y, N, the <RETURN> key, or the <ESCAPE> key (if escape 
recognition is enabled). 


~-ASKN - ASK FOR DEFINITION OF A NUMERIC SYMBOL 


4.9 .ASKN - ASK FOR DEFINITION OF A NUMERIC SYMBOL 


The .ASKN directive prints on the terminal screen a request for a 
numeric value, waits for it to be entered, optionally tests the 
range for the numeric response and/or applies a default value, 
and sets the specified symbol accordingly. 


If the symbol has not previously been defined, Indirect makes’ an 
entry in the symbol table. If the symbol has already been 
defined, Indirect resets its value in accordance with the reply. 
Indirect exits with a fatal error if the symbol was previously 
defined as a logical or string symbol. 


Formats (brackets are required syntax) 


-ASKN ssssss txt-strng 
-ASKN [low:high:default:timeout] ssssss txt-strng 


where: 


SSSSSS The 1- to 6-character symbol to be assigned a 
numeric value. 


txt-strng The question or prompt that Indirect displays. 


low:high A numeric expression giving the range for the 
response. 
default A numeric expression or symbol giving the 


default value. 


timeout The timeout count. Indirect waits this long for 
a response, then applies the default answer. 
The format for timeout is nnu, where nn is the 
decimal number of time units to wait and u is T 
(ticks), S (seconds), M (minutes), or H (hours). 
The timeout count is valid only if timeout mode 
is enabled (.ENABLE TIMEOUT). 


The entire .ASKN statement must fit on one command line. 


Note that if you omit any of the parameters within the square 
brackets, any preceding colons are required for positional 
identification. 


The command line cannot exceed 132 (decimal) characters in 
length. When executing an  .ASKN directive, Indirect displays 
txt-strng prefixed by an asterisk and suffixed with [0]: EG 
indicate that the response is considered as octal or [D]: to 
indicate that the response is considered as decimal. The reply 
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must be a number either within the specified range or in the 
range 0 through 177777 (octal) (by default) or 0 through 65535 
(decimal). 
If the response is outside the specified range, the message 

IND -- VALUE NOT IN RANGE 
is displayed and the query repeated. 
If an arithmetic operation yields a result greater than 177777 
(octal) when computing the actual value of any of the arguments 
(low, high, or default), a fatal error occurs and the message 

IND -- NUMERIC UNDER- OR OVERFLOW 
is displayed. 
If the response is an empty line (null) and a default value 
(default) was not specified, Indirect applies a default of 0. 
Note that in this case, the range, if specified, must include 0. 
The response may be either octal or decimal; a leading pound sign 
(#) forces octal, a trailing period (.) forces decimal. In the 
absence of both, Indirect applies a default radix. The default 
radix is decimal if either the range or default values are 
decimal expressions (followed by a _ period). Otherwise, the 
default radix is octal (unless decimal mode has been enabled). 


Indirect displays the default type as either [0] or [D]. 


To force a default decimal radix without specifying a range 
argument, use the following construction: 


~-ASKN [::0.] A ENTER VALUE 
or 


.ENABLE DECIMAL 
-ASKN A ENTER VALUE 


Examples 
@® The directive statement: 
-ASKN SYM DEFINE NUMERIC SYMBOL A 
displays 
S * DEFINE NUMERIC SYMBOL A [O]: 


on the terminal screen where: 
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-ASKN - ASK FOR DEFINITION OF A NUMERIC SYMBOL 


fO] is the default radix (octal). 


Indirect then defines symbol SYM according to the reply 
entered. 


The directive statement: 

~-ASKN [2:35:16:20S] NUMSYM DEFINE NUMERIC SYMBOL A 
displays 

S * DEFINE NUMERIC SYMBOL A [O R:2-35 D:16 1T:20S]: 
in the format [x R:low-high D:default T:timeout] 


where: 


x O if the default radix is octal or D if 
it is decimal. 


R:low-high The specified range. 
D:default The specified default. 


T:timeout The specified timeout count before the 
default answer is applied. 


Indirect then checks that the response string is in the 
specified range. 


The directive statement: 
-ASKN [NUMSYM+10:45:NUMSYM+10] SYM DEFINE NUMERIC SYMBOL B 
displays (assuming the value of 16 octal for NUMSYM): 


S * DEFINE NUMERIC SYMBOL B [O R:26-45 D:26]: 


-ASKS - ASK FOR DEFINITION OF A STRING SYMBOL 


4.10 .ASKS - ASK FOR DEFINITION OF A STRING SYMBOL 


The .ASKS directive prints on the terminal screen a request for a 
String value to define a specified symbol and optionally tests 
that the number of characters in the response string falls within 
the specified range. 


If the symbol has not previously been defined, Indirect makes an 
entry in the symbol table. If the symbol has already been 
defined, Indirect resets its value in accordance with the reply. 
Indirect exits with a fatal error if the symbol was defined 
previously as a logical or numeric’ symbol. If the number of 
characters is out of the specified range, the message 

IND -- STRING LENGTH NOT IN RANGE 
is displayed and the question repeated. 
Formats (brackets are required syntax) 


-ASKS ssssss txt-strng 
-ASKS [low:high:default:timeout] ssssss txt-strng 


where: 


SSSSSS The 1- to 6-character symbol to be assigned a 
String value. 


txt-strng The question or prompt that Indirect displays. 


low:high A numeric expression giving the range for the 
number of characters permitted in the response 
string. 

default A string expression or symbol giving the default 
value. 

timeout The timeout count. Indirect waits this long for 
a response, then applies the default answer. 


The format for timeout is nnu, where nn is_ the 
decimal number of time units to wait and u is T 
(ticks), S (seconds), M (minutes), or H (hours). 
The timeout count is valid only if timeout mode 
is enabled (.ENABLE TIMEOUT). 


The entire .ASKS statement must fit on one command line. 
Note that if you omit any of the parameters within the square 


brackets, any preceding colons are required for positional 
identification. 


-ASKS - ASK FOR DEFINITION OF A STRING SYMBOL 


When executing an .ASKS directive, Indirect displays txt-strng 
prefixed by an asterisk (*) and suffixes it with [S]:. The reply 
must be an ASCII character string. 


Examples 
@ The directive statement: .ASKS NAM PLEASE ENTER YOUR NAME 
displays 


S * PLEASE ENTER YOUR NAME [S]: 


on the terminal screen. Indirect then defines symbol NAM 
according to the string reply entered. 


® The directive statement: 
-ASKS [1:15::10S] MIDNAM PLEASE ENTER YOUR MIDDLE NAME 
displays 
S * PLEASE ENTER YOUR MIDDLE NAME [S R:1-15 T:10S]: 


in the format [S R:low-high T:timeout] 


where: 
S The symbol type (string). 
R:low-high The specified range for number of 
characters. 
Le CLmeoue The specified timeout count. 


.BEGIN - BEGIN BLOCK 


4.11 .BEGIN - BEGIN BLOCK 


The .BEGIN directive marks the beginning of a Begin-End block. 
The block must be terminated with an .END directive. 


Labels and local symbols defined following the .BEGIN directive 
are local to the block instead of being used throughout the 
entire command file. Therefore, labels and local symbols defined 
inside a block lose definition outside the block. (Labels and 
symbols defined outside a block retain definition throughout the 
file.) Labels and symbols defined outside a block and then 
modified within the block, however, assume and retain the value 
assigned in the block. 


Labels and local symbols defined within a block lose definition 
with an .ERASE LOCAL directive statement or with the .END 
directive. 
.BEGIN must be the only directive on a command line. FOr 
example, the .BEGIN directive cannot appear on the same line as 
an .IF directive. 
Format 

. BEGIN 


as the only directive on the line. 


.CHAIN - CONTINUE PROCESSING USING ANOTHER FILE 


4.12 .CHAIN - CONTINUE PROCESSING USING ANOTHER FILE 


The .CHAIN directive closes the current file, erases all local 
symbols, clears any .ONERR arguments, empties the direct access 
label cache, and continues processing using command lines’ from 
another file. However, the .CHAIN directive does not close data 
files or change the nested-file level. 
Format (brackets not part of syntax) 

.CHAIN filename[/switches] 
where filename is the name of the file that contains the new 
command lines. The /switches are any of the optional switches 
described in Section 4.5. 
Example 
The directive statement: 


.CHAIN OUTPUT 


fransters: control to the file OUTPUT.CMD: 


-CLOSE - CLOSE SECONDARY FILE 


4.13 .CLOSE - CLOSE SECONDARY FILE 


The .CLOSE directive closes the secondary file opened by an .OPEN 
directive. 


Format (brackets not part of syntax) 


.CLOSE [#n] 

where: 

#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric symbol 
for the value n by enclosing the symbol ia 
apostrophes. 


-DATA - OUTPUT DATA TO SECONDARY FILE 


4.14 .DATA - OUTPUT DATA TO SECONDARY FILE 


The .DATA directive specifies text that is to be output to a 
secondary file previously opened by an .OPEN directive. 


When Indirect processes the text string that follows the .DATA 
directive, it ignores a leading space (if present), assuming it 
to be a separator between the directive and the text string. Any 
other spaces or tabs are transferred to the data file. 


Format (brackets 


not part of syntax) 


.DATA [#n] txt-strng 


where: 
txt-strng 


#n 


The command line 
specified text 


The text to be output to the secondary file. 


An optional file number in the range 0 to 3. 
The default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol 
in apostrophes. 


Cannot exceed 132 (decimal) characters and the 
string cannot continue onto the next line. If a 


secondary file is not open, an error condition exists; Indirect 
issues an error message and begins error processing. 


Example 


.SETS SEND "THIS IS DATA" 


~OPEN TEMP 
-_DATA ‘SEND’ 
‘CLOSE 


These directives 


output THIS IS DATA to the secondary file 


TEMP.DAT (.DAT is the default file type for a data file). 


.DEC - DECREMENT NUMERIC SYMBOL 


4.15 .DEC - DECREMENT NUMERIC SYMBOL 


The .DEC directive decrements a numeric symbol by one. Indirect 
exits with a fatal error if the symbol was defined previously as 
a logical or string symbol. 
Format 

.DEC SSSSSS 
where: 

SSSSSS The 1- to 6-character numeric symbol. 
Example 


«DEC LOOPCT 


This directive decrements by 1 the value assigned to the numeric 
symbol LOOPCT. 


-DELAY - DELAY EXECUTION FOR A SPECIFIED PERIOD OF TIME 


4.16 .DELAY - DELAY EXECUTION FOR A SPECIFIED PERIOD OF TIME 


The .DELAY directive delays further processing of the file for a 
specified period of time. 


Format 
-DELAY nnu 
where: 
An The decimal number of time units to delay. 
u TT = ticks 
S - seconds 
M - minutes 
H - hours 


The parameter nn is decimal by default. 


If quiet mode is disabled when the .DELAY directive is executed, 
Indirect issues the message: 


IND -- DELAYING 


When the time period expires and the task resumes, Indirect 
issues the message: 


IND -- CONTINUING 
Example 
The directive statement: 
.DELAY 20M 


delays processing for 20 (decimal) minutes. 


sUDIT SABLE. = DISABLE OPTION 


4.17 .DISABLE - DISABLE OPTION 


The .DISABLE directive disables a specified operating mode 
previously activated by an .ENABLE directive. 


Format 
.-DISABLE option[,option.. .} 


The following is a list of the operating modes that can be 
disabled: 


ATTACH DETACH GLOBAL TIMEOUT 
CONTROL-Z DISPLAY LOWERCASE TRACE 

DATA ESCAPE CLI TRUNCATE 
DECIMAL ESCAPE-SEQ OVERFLOW SUBSTITUTION 
DELETE QUIET 


Note that when you disable detach mode from a command file and 
then request a task or DCL command to display information, the 
command file may not be able to continue executing. The task or 
DCL command may need to attach to the terminal to display the 
information but will not be able to do so because Indirect cannot 
detach from the terminal. 


-ENABLE - ENABLE OPTION 


4.18 .ENABLE - ENABLE OPTION 


The .ENABLE directive is used to invoke several operating modes. 
Each mode is independent of the others; all of them can be active 
Simultaneously. When Indirect starts to process a file, the 
initial settings are: 


ATTACH enabled GLOBAL enabled 
CONTROL-Z disabled LOWERCASE enabled 
DATA disabled Cid enabled 
DECIMAL disabled OVERFLOW disabled 
DELETE disabled QUIET disabled 
DETACH enabled SUBSTITUTION enabled 
DISPLAY enabled TIMEOUT enabled 
ESCAPE disabled TRACE disabled 
ESCAPE-SEQ disabled TRUNCATE disabled 


In attach mode, Indirect attaches to the screen when displaying 
comment lines. In detach mode, it detaches from the screen when 
processing command lines. Enabling both of these modes allows 
you to type CTRL/O to suppress a lengthy comment. 


Enabling Control-Z mode allows a command file to detect a CTRL/Z 


response to a question and continue processing. If Control-zZ 
mode is disabled and you type CTRL/Z in response to an .ASKx 
question, Indirect exits. If Control-Z mode is enabled, the 


Special symbol <EOF> is set to true and Indirect continues 
processing the command file. 


In data mode, Indirect outputs lines that follow an .ENABLE DATA 
directive statement to a secondary file. (The .DATA directive 
sends a single line of text to a secondary file.) To disable data 
mode, the .DISABLE DATA statement must begin in the first column. 
Otherwise, Indirect copies the statement itself into the data 
file. The .ENABLE DATA directive also has an optional argument 
(#n) that specifies which file the data is to go into. See the 
description of the .DATA directive for more information. 


In global symbol mode, symbol names that begin with a dollar sign 
(S$) are defined as global to all levels of indirect files; once 
such a symbol has been defined, all levels recognize it. Symbols 
that do not begin with a dollar sign are recognized only within 
the level that defines them. 


In decimal mode, all numeric symbols are created or redefined by 
default as decimal instead of as octal. 


In delete mode, the current command file is deleted when Indirect 
processes the last command line in the file. 
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In display mode, Indirect displays the current fields for the 
-ASKx directives and @ <EOF>. If display mode is disabled, 
Indirect displays only the text string for the .ASKx directive 
and suppresses @ <EOF>. 


In CLI mode, commands not processed by Indirect are passed _ to 
DCL. CLI mode is equivalent to the functions of the /CLI switch. 


In lowercase mode, characters read from the terminal in response 
to .ASKS directives are stored in the string symbol without 
lower- to uppercase conversion. The representation of characters 
is significant when comparing strings since the .IF directive 
distinguishes between lowercase and uppercase characters. 


In substitution mode, Indirect substitutes a string for a symbol. 
The symbol must begin and end in apostrophes (’symbol’). For 
example, if the symbol A has been assigned the string value THIS 
IS A TEST, then every ’A’ will be replaced by THIS IS A TEST. 
When substitution mode is enabled, Indirect performs 
substitutions eg each line before scanning the line _ for 
directives and DCL commands. 


Escape recognition (.ENABLE ESCAPE) permits the response to an 
.ASK,  .ASKN, or .ASKS' directive to be an escape character. A 
question answered with a single escape character sets the special 
logical symbol <ESCAPE> to true. The escape character must be 
used only as an immediate terminator to the question; if one _ or 
more characters precede the escape character, an error condition 
exists. In this case, the message 


IND -- INVALID ANSWER OR TERMINATOR 


is printed and the question repeated. Note that if you press the 
<ESCAPE> key in response to an .ASK directive, the specified 
logical symbol (ssssss of .ASK ssssss txt-strng) is also set to 
true. 


Escape-sequence recognition (.ENABLE ESCAPE-SEQ) forces Indirect 
to attach to the terminal for escape-sequence recognition, using 
the IO.ATT!TF.ESQO I/O function. 


In this mode, the result of an .ASKx or .READ statement from the 
terminal will contain the terminating escape character and escape 
sequence, as documented in the P/OS System Reference Manual. 


Overflow mode allows signed arithmetic in numeric expressions. 
Enabling the mode provides for numeric expressions and operations 
that otherwise would result in the "Numeric under- or overflow" 


error message. 


In quiet mode, Indirect does not echo DCL command lines or 
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comments. The command lines are executed normally and, if they 
return a message or display, the message or display is printed on 
the screen. 


In timeout mode, Indirect uses the timeout parameters specified 
with the .ASKx directives. Indirect waits for the timeout count 
to elapse and then applies the default answer to the directives. 
Timeout mode must be enabled (the default) to use the timeout 
counts for the .ASKx directives. 


In trace mode, command lines that Indirect has processed are 
displayed on the terminal screen. As each line is processed, it 
is displayed with its nesting level and an exclamation mark (!). 
Trace mode is equivalent to the function of the /TR switch. 


In truncate mode, Indirect ignores any truncate errors on a .READ 
directive. A truncate error occurs when a line ina file is too 
Lond. If the full record cannot Lit within the LS2 
(decimal)-character limit of the symbol, the record is truncated. 
Formats (brackets not part of syntax): 

ENABLE: GpU10n[ ,OpU1On «~~ | 


.ENABLE DATA [#n] 


where: 

#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric symbol 
for the value n by enclosing the symbol on 
apostrophes. 

Examples 


6 Substitution mode: 


-ENABLE SUBSTITUTION 
<ASKS FIL SPECIFY SOURCE FILE 
MACRO ‘FIL’ 


When the file is executing, the corresponding lines displayed 
at the terminal screen are: 


> * SPECIPY: SOURCE FILE (Sj SOURCE 
S MACRO SOURCE 


~-ENABLE - ENABLE OPTION 


® Control-Z mode: 


-ENABLE CONTROL-Z 

-ASK RESP DO YOU WISH TO CONTINUE 
wht <BOR> ~<GOTO-CLENUP 

wLEP REGED ~GOLO-CLENUP 


If you type CTRL/Z in response to the question, <EOF> is set 
to true and Indirect transfers to CLENUP. 


»~-END - END BLOCK 


4.19 .END - END BLOCK 


The .END directive marks the end of the Begin-End block. LE 
Indirect encounters more .END directives than .BEGIN directives, 
command processing terminates and the following message is 
displayed: 

IND -- ILLEGAL NESTING 
Format 

. END 


as the only directive on the line. 


.ERASE - DELETE SYMBOLS 
4.20 .ERASE - DELETE SYMBOLS 


The .ERASE directive deletes all local or global symbol 
definitions, or a specific global symbol definition. When you 
define a symbol, either locally (by defining a symbol value) or 
globally (by enabling global symbol mode and preceding the symbol 
name with a dollar sign ($)), Indirect creates an entry in the 
symbol table. The .ERASE directive erases either all local or 
all global entries, or a specific global entry, in the table. 


Following an .ERASE directive, you can redefine symbol values as 
well as symbol type. 


Formats 
-ERASE LOCAL 
-ERASE GLOBAL 
.ERASE SYMBOL global-symbol 


An .ERASE LOCAL directive outside of a Begin-End block erases all 
local symbols defined within the current file. 


An .ERASE LOCAL directive within a Begin-End block erases only 
those local symbols defined within the block. 


However, note that the following actions also occur: 


1. Local symbols defined within a nested file are erased 
when that file exits. 


2. Local symbols defined within a Begin-End block are 
erased with .END. 


3. Local symbols defined outside of Begin-End blocks are 
visible, modifiable, and not erasable within a Begin-End 
block. 


An .ERASE GLOBAL, either outside of or within a Begin-End block, 
erases all global symbols. 


An .ERASE SYMBOL global-symbol erases the specified global 
symbol. (Individual local symbols are not erasable.) 


-ERASE - DELETE SYMBOLS 


Example 
.ERASE LOCAL 


This directive erases all local symbol definitions used in the 
indirect command file. 


.ERASE SYMBOL SSWITC 


This directive erases the single global symbol "SSWITC." 


-EXIT - EXIT CURRENT COMMAND FILE 


4.21 .EXIT - EXIT CURRENT COMMAND FILE 


The .EXIT directive terminates processing of the current command 
File or Begin-End block and returns control to the previous-level 
command file or, if the directive is executed within a block, to 
the line following the .END directive. If the directive is 
encountered at the uppermost indirect nesting level, Indirect 
exits and passes control to DCL (see the .STOP directive). 


The .EXIT directive also allows you to optionally specify a value 
to copy into the special symbol <EXSTAT>. 


Format (brackets not part of syntax) 
EXIT [value] 
where value is an optional numeric expression copied to <EXSTAT>. 
Examples 
The following line is in an indirect command file called TESTI: 
GTEST2 
The file TEST2.CMD contains the following line: 
vex TL 


When Indirect encounters the .EXIT directive in TEST2, control 
returns to TEST1.CMD. 


If the .EXIT directive in TEST2.CMD includes a numeric 
expression, for example: 


~EXIT N+2 


Indirect evaluates the expression and copies the value into 
<EXSTAT>. 


sFORM = ACCESS FORM DRIVER 


4.22 .FORM - ACCESS FORM DRIVER 


The .FORM command provides access to the PRO/FMS-11 form driver 
from a command file. You can specify commands in the command 
file that perform operations such as: 


@® Directing the display of a form 

@ Directing the motion of the cursor from field to field 

@ Acquiring and parsing the user typein 
The syntax of the .FORM command parallels the format of the 
MACRO-11 call interface to FMS-11. For details, see _ the 


FMS-11/RSX Software Reference Manual, particularly the chapters 
on form driver operation and the MACRO-11 interface. 


Format 

FORM ENC; DL p2y3250n 

where: 

FNC is a three-letter code indicating which FMS 
operation is to be performed. These codes 
are a subset of the codes used in _ the 
MACRO-11/FMS interface and are summarized 
below. 

od eer ©) 2! are string or numeric symbols or constants 


conforming to Indirect syntax rules. 


Formal parameters: 


LINENUM The screen line number where form display is 
to begin. 
RETTRM The name of a numeric variable to contain the 


code for the terminator typed by the user. 


FILENAME The name of a string variable or string 
constant naming the file in which the form 
definitions are stored. 


RETNAM The name of the field completed by the user. 
RETINX The index of the field completed by the user. 
TERMINATOR The code for the terminator to be processed. 
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VALUE A string variable or constant to be placed in 
the indicated field. 

FORMNAME The name of the form to display. 


FLDNAME The name of a field defined in the currently 
displayed form. 


INDEX In an indexed field, the index referencing 
the specific field being addressed. 


RETVAL The name of a string variable into which the 
returned value will be placed. 


Examples 

String values supplied as input to the .FORM command can be 
expressed aS a constant enclosed in quotation marks or as the 
name of a previously defined string variable. For example, the 


following have equivalent results: 
-FORM OPN, "FMSDEM.FLB" !'define form library filename 
and 


.SETS LIBR "FMSDEM.FLB" 
-FORM OPN,LIBR 'define form library filename 


String and numeric values returned as output from the .FORM 
command are passed as though a .SETS or .SETN command were being 
executed. This means that the name of the variable to receive 
the value must be supplied, and that it must either have not been 
defined or is previously defined as the appropriate string or 
numeric type. For example: 


-FORM GET, "CHOICE",,,,FLDVAL ! return value of field 
"CHOICE" 


The Indirect local symbol FLDVAL is defined or redefined as 
required and contains the string typed by the user to fill the 
field named CHOICE on the currently displayed form. 


Remember that Indirect can handle strings only as long as 132. 
characters, so that values returned to strings from the form 
driver must be shorter than that length. This 12S partacularly 
important with the ALL and RAL commands, which attempt to place 
the string values of all fields displayed on the form into a 
Single Indirect string variable. A better programming practice 
would be to use a series of GET commands addressing each 


4-51 


sf ORM. = ACCESS -PORM DRIVER 


individual field. 


A demonstration procedure is included in LB:[1,2]INDSYS.CLB. 
This procedure Library 1s packaged on the PRO/Tool Kit 
distribution kit. To execute the demonstration procedure, type 
the following command line: 


S @LB:[1,2]INDSYS.CLB/LB: FMSDEM 
After the terminal type setting is verified, a temporary copy of 
the forms library is placed in your directory. The procedure is 
identical to that provided in MACRO-11 form on the FMS-11/RSX 
ee ie a Refer to the FMS-11/RSX Software Reference Manual for a 
complete description of this demonstration. 
Using the following DCL command, extract the FMS demonstration 
procedure and use it as an extended example for building your own 


command procedures. 

S LIBRARIAN/EXTRACT/OUT=FDEM.CMD LB:[1,2]INDSYS.CLB FMSDEM 
Commands: 
CSH -- Clear screen and show form 

.FORM CSH, FORMNAME [,LINENUM] 


The form driver clears the entire screen and displays’ the 


Specified form from the currently open form library. If 
LINENUM is supplied, it 1s interpreted as an integer line 
number which overrides the form starting line number 


supplied by the forms editor. 
SHO -- Show form 
.FORM SHO, FORMNAME [,LINENUM] 


The form driver clears only the portion of the screen 
required for the specified form, then displays the form 
named in FORMNAME from the currently open forms library. If 
LINENUM is present, it overrides the starting line number 
supplied by the forms editor. 


GET -- Get value for specified field 


.FORM GET, FLDNAME [,INDEX [,RETNAM [,RETINX [,RETVAL 
[7 RETTRM | yg 


The form driver places the cursor at the initial position of 
the specified field and accepts input from the keyboard for 
that field. 


~-FORM - ACCESS FORM DRIVER 


ANY -- Return any field value 
.FORM ANY ,RETNAM ,[RETINX] ,RETVAL [,RETTRM] 
The form driver waits for the operator to fill any field. 
The cursor may be positioned in a field that is not 
display-only. The field name and its resulting value are 
returned. 

ALL -- Return all fields 
.FORM ALL [,RETVAL [,RETTRM] ] 


After the operator has filled any or all fields of a form 
and presses the <ENTER> key, the form driver returns all 
field values as a concatenated string into the string 
variable RETVAL. Remember that strings may have a maximum 
length of 132. characters so that the concatenated value 
may not exceed this length. 


DAT -- Get named data from form 
.FORM DAT, FLDNAME, [INDEX], RETVAL 


The form driver returns the value from the named data 


portion of the form. Tf. INDEX as supplied; 1 ts 
interpreted as the index for the named data value to be 
returned. 

GSC -- Get current line of scrolled area 


-FORM GSC, FLDNAME, RETVAL [,RETTRM] 


The form driver returns the contents of the entire current 
scrolled data line as a concatenated string. . 


CLS -- Close forms library 
*FORM Cis 
The currently open forms library is closed. 
OPN -- Open forms library 
«FORM OPN, FILENAME 
The forms driver attempts to open the specified file as a 


library of form definitions. The library is built by the 
Forms ULLIAty: program: 


~-FORM - ACCESS FORM DRIVER 


PSC -- Put to current line of scrolled area 
-FORM PSC, FLDNAME, VALUE 
The form driver outputs the data specified to the current 


line of the scrolled area. The scrolled area is identified 
by naming in FLDNAME any field in that area. 


TRM -- Process field terminator 
.FORM TRM, [FLDNAME], [VALUE], TERMINATOR [,RETNAM 
[, RETINX] ] 


The user supplies the numeric code for the terminator, 


processed in TERMINATOR. The form driver then performs 
cursor and field positioning accordingly. The FMS-11/RSX 
Software Reference Manual describes terminator codes and 
actions. 

PUT -- Put to specified field 


~FORM PUT, FLDNAME, [INDEX], VALUE 

This displays the value specified in the named field. 
PAL -- Put all fields 

.FORM PAL [,VALUE] 


The contents of VALUE are used to fill all fields of the 


current form. Remember that the VALUE string may have a 
maximum of 132. characters. 
LST -- Output to last line of screen 


.FORM LST [,VALUE] 
The form driver clears the last line of the screen and 
displays the specified string. (The last line is not 
normally accessible via a form.) This is the only way to 
display messages in this screen location. 

RAL -- Return all fields 
-FORM RAL, VALUE 

RTN -- Return value for specified field or for all fields 


.FORM RTN, [FLDNAME] , [INDEX], RETVAL 


If the FLDNAME parameter is not present the form driver 


4-54 


-FORM - ACCESS FORM DRIVER 
returns the concatenated string of the current values for 
all fields in the form. See the note under the ALL command. 


If FLDNAME is present, the form driver returns the value 
only for the named field. 


SPN/SPF -- Supervisor mode control 
-FORM SPN 
-FORM SPF 
Turn supervisor mode on (SPN) or off (SPF). The form editor 


permits defining some fields as display only if supervisor 
mode is off. 


.GOSUB - CALL A SUBROUTINE 
4.23. .GOSUB - CALL A SUBROUTINE 


The .GOSUB directive saves the current position in an indirect 
command file and then branches to a label. The label identifies 
an entry point to a subroutine that is terminated by a .RETURN 
directive. 


When you issue a .GOSUB directive from within a Begin-End block, 
Indirect saves the current block context and then scans down the 
file searching for the first occurrence of the subroutine label. 
Note that during the scan, Indirect ignores any intervening 
-BEGIN or .END directives. The .RETURN directive restores 
previous block context. Thus, the subroutine can be contained 
within a Begin-End block. 


The maximum nesting depth for subroutine calls is 8. 
Format 

.GOSUB label parameters 
where label is the label that designates the first line of a 
subroutine, but without the leading period and trailing colon. 
Any parameters to the right of the label and to the left of a 
comment are transferred to the reserved local symbol COMMAN. The 
value of COMMAN can then be parsed with the .PARSE directive to 
obtain formal call parameters. 
Example 
The directive statement: 


~-GOSUB EVAL 


transfers control to the subroutine labeled .EVAL:. 


.GOTOQ - BRANCH TO A LABEL 


4.24 .GOTO - BRANCH TO A LABEL 


The .GOTO directive causes a branch from one line in an indirect 
command file to another. All commands between the .GOTO 
directive and the specified label are ignored. Branches can _ go 
forward or backward in the file. 


The target of a .GOTO branch from within a Begin-End block must 
be contained in that block. The .GOTO directive cannot branch 
into another block. When Indirect encounters a .GOTO directive 
within a Begin-End block, it searches for the specified label in 
Chat. DLock. 


Since Indirect only searches the one Begin-End block, you can use 
the same label more than once in a command file. 


Format 
.GOTO label 


where label is the name of the label, but without the leading 
period and trailing colon. 


Example 
The directive statement: 
.GOTO 100 


transfers control to the line containing the label .100:. 


-IF ~ TEST IF SYMBOL SATISFIES SPECIFIED CONDITION 


4.25 .IF - TEST IF SYMBOL SATISFIES SPECIFIED CONDITION 


The .IF directive compares a numeric or string symbol with 
another expression of the same type to determine if one of 
several possible conditions is true. If the condition is 
Satisfied, Indirect executes the remainder of the command line. 


When comparing a string symbol with a string expression, Indirect 
compares the ASCII values of each operand’s characters (from left 
to right) one by one. An operand is considered greater if the 
Eirst nonequal character has a greater value than _ the 
corresponding character in the other operand. Numeric symbols 
are compared strictly on the basis of magnitude. 


Format 


-IF symbol relop expr directive-statement 


where: 
symbol The 1- to 6-character numeric or string 
symbol. 
relop One of the following relational operators: 
EQ or = - Equal to 
NE or <> - Not equal to 
GE or >= - Greater than or equal to 
LE or <= - Less than or equal to 
GT or > - Greater than 
LT or < - Less than 
expr An expression of the same type as symbol. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 
~SETS X "A" 
soEIs-Y “ae 


LF xX LY Y «GOTO 200 


The ASCII value of string symbol X is less than the ASCII value 
of string symbol Y, which satisfies the less-than condition. 
Thus, control passes to the line containing the label .200:. 


-SETN Ni 2 


OBIN NZ: 7 
-IF Nl <= N2 DIRECTORY/FULL 
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With the condition satisfied (numeric symbol Ni less than or 
equal to numeric symbol N2), the DIRECTORY command is processed. 


{SETS ST “AAB* 

.SETS S2 “AA" 

.SETS S3 "BBBB" 

.IF S1 >= $2+S3[{1:1] .INC N 


The condition is satisfied where string symbol Si is greater than 
or equal to the concatenation of string symbol S2 and the first 
character of string symbol S3 (AAb >= AAB). Therefore, Indirect 
increments numeric symbol N. 


-IFACT/.IFNACT - TEST IF TASK IS ACTIVE OR DORMANT 


4.26 .IFACT/.JFNACT - TEST IF TASK IS ACTIVE OR DORMANT 


The .IFACT or .IFNACT directive tests whether a task iS active 
(.IFACT) or dormant (.IFNACT). If the test is true, the rest of 
the command is processed. If the specified task is not 
installed, Indirect assumes the dormant condition. 

Formats 


.ILFACT taskname directive-statement 


-LFNACT taskname directive-statement 


where: 
taskname A 1- to 6- character legal task name. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 

Examples 


sl PACT REPORT .GOTO 350 


-IFNACT REPORT RUN REPORT 


JL DE/ si PEP NDE = “TeST LP SYMBOL, DEFINED “OR: NOT DEFINED 


4.27 .IFDF/.JFNDF - TEST IF SYMBOL DEFINED OR NOT DEFINED 


The .IFDF or .IFNDF directive tests whether a logical, numeric, 
or string symbol has been defined (.IFDF) or not defined 
(.IFNDF). If the test is true, the rest of the command line is 
processed. This directive does not test the value of the symbol. 
Formats 


-IFDF ssssss_ directive-statement 


-IFNDF ssssss7 directive-statement 


where: 
SSSSSS The 1- to 6-character symbol being tested. 
The symbol can be local, global, or an 
Indirect special symbol. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 


-IFDF A .GOTO 100 


.IFNDF A .ASK A DO YOU WANT TO SET TIME 


-IFINS/.IFNINS - TEST IF TASK INSTALLED OR NOT INSTALLED 


4.28 .IFINS/.JFNINS - TEST IF TASK INSTALLED OR NOT INSTALLED 


The .IFINS or .IFNINS directive tests whether a task is installed 
(.IFINS) or not installed (.IFNINS) in the system. If the test 
is true, the rest of the command line is processed. 

Formats 


-LFINS taskname directive-statement 


.LFNINS taskname directive-statement 


where: 
taskname A 1- to 6-character task name. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 
~LFINS teaPIP <GOTO .250 
.LTFNINS -eePiP’ INS: DWL2(Z2TKT)|PIPRES.2SK 


.-ITFENABLED/.IFDISABLED - TEST IF MODE ENABLED OR DISABLED 


4.29 .IFENABLED/.IFDISABLED - TEST IF MODE ENABLED OR DISABLED 


The .IFENABLED or .IFDISABLED directive tests whether an 
operating mode has been enabled with the .ENABLE directive or 
disabled with the .DISABLE directive. (See the description of 
the .ENABLE directive for the list of operating modes.) 
Formats 

.IFENABLED option directive-statement 


.IFDISABLED option directive-statement 


where: 
option The same operating mode option (with the 
exception of DATA) used with the .ENABLE or 
.DISABLE directive. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 


-IFLOA/.IFNLO - TEST IF DRIVER LOADED OR NOT LOADED 


4.30 .IFLOA/.IFNLO - TEST IF DRIVER LOADED OR NOT LOADED 


The .IFLOA or .IFNLOA directive tests whether a driver is loaded 
(.IFLOA) or not loaded (.IFNLOA) in the system. If the test is 
true, the rest of the command line is processed. For purposes of 
this directive, resident drivers are considered loaded. 
Formats 

-IFLOA dd: directive-statement 


.ILFNLOA dd: directive-statement 


where: 
dd: A device driver. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 
-L[FLOA XK: .GOTO 250 
.LFNLOA XK: ;Sorry, XK Driver not available 


eLEt/ ete = TEST EF SYMBOL: “TRUE “OR BALSE 


4.31 .IFT/.IFF - TEST IF SYMBOL TRUE OR FALSE 


The .IFT or .IFF directive tests whether a logical symbol is true 
or false. If the test is true, Indirect processes the rest of 
the command line. 


Indirect exits with a fatal error if the tested symbol was 
previously defined as a numeric or string symbol. 


Formats 
-IFT ssssss7 directive-statement 


-LFF ssssss_ directive-statement 


where: 
SSSSSS The 1- to 6-character logical symbol being 
tested. 
directive- The Indirect command line to be processed 
statement if the condition is satisfied. 
Examples 


.IFT A  .GOTO 100 


TRE “Be «GOTO: 200 
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4.32 .INC - INCREMENT NUMERIC SYMBOL 


The .INC directive increments a numeric symbol by one. Indirect 
exits with a fatal error if the symbol was previously defined as 
a logical or string symbol. 
Format 

»-LNC. SSSsss 


where: 


SSSSSS The 1- to 6-character numeric symbol being 
incremented. 


Example 
.INC B 


Increment by 1 the value assigned to the numeric symbol B. 
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4.33 .label: - DEFINE A LABEL 


Labels always appear at the beginning of the line; they may be on 
a line with additional directives and/or a DCL command, on a line 
with a comment, or on a line by themselves. When control passes 
to a line with a label, the line is processed from the first 
character after the colon. 


Commands do not have to be separated from the label by a space. 
Only one label is permitted per line. Labels are one through six 
characters in length and must be preceded by a period and 
terminated by a colon. A label may contain only alphanumeric 
characters and/or dollar signs (S$). 


It is also possible to define a label as a direct access’ label; 
once the label is found, its position in the command file is 
saved. This allows subsequent jumps to frequently-called labels 
or subroutines to be effected quickly. The first statement 
processed after a jump to a direct access label is the one on the 
next line. The maximum number of direct access labels you can 
define within an indirect command file is 16. If you define more 
than the maximum number allowed, the subsequent direct access 
labels replace the earliest, and so on. 


To declare a label for direct access, leave the line following 
the colon blank. 


Example 

100% .ASK A DO YOU WANT TO CONTINUE? 
.IFT A .GOSUB 200 

~200% 


-;THIS IS THE START OF A SUBROUTINE 


. RETURN 


~-ONERR - BRANCH TO LABEL ON DETECTING AN ERROR 


4.34 .ONERR - BRANCH TO LABEL ON DETECTING AN ERROR 


If Indirect detects one of the errors list below, control passes 
to the line containing the specified label. This feature 
provides you with a means of gaining control to terminate command 
File processing in an orderly manner. 

o Undefined symbol 

o Bad syntax 

Oo Unrecognized command 

o String substitution error 


O “SYMDOL *Cyoe: error ‘Coley «LPT, «LERs «<1NGy. 2DEC) 


o Redefinition of a symbol to a different type (.ASK, .ASKN, 
sAOKOy 20m, “oele ; wobbly aSEIN:: «SBED,. ~<SETO> .SHEES) 


o Data file error (.OPEN, .OPENA, -OPENR, .DATA, ‘CLOSE, GF 
-.READ between .ENABLE DATA and .DISABLE DATA) 


Note that the .ONERR directive applies only to the error 
conditions listed; errors returned from a task external to 
Indirect (for example, a DCL syntax error) are not processed by 
the .ONERR directive. 
Format 

-ONERR label 


Upon detecting an error, the processor passes control to the line 


starting with .label:. The .ONERR directive must be issued 
before Indirect encounters the error condition. If the directive 
is executed (one of the listed errors is encountered), error 


processing passes to the specified label. If the label specified 
by the .ONERR directive does not exist and an error condition has 
occurred, command processing terminates. 


Once an .ONERR condition has occurred, another .ONERR directive 
must be issued to trap a future error. 


Example 
-ONERR 100 
Upon: detecting one of ‘the. -error ‘conditions, Indirect passes 


control to the line tabe Led oO. 
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~OPEN = OPEN SECONDARY FILE 


4.35 .OPEN - OPEN SECONDARY FILE 


The .OPEN directive opens a specified secondary file as an output 
File. The .DATA directive is used to place data in this 
secondary file. 

Format (brackets not part of syntax) 


.OPEN [#n] filename 


where: 

Filename A file to be opened as an output file. The 
default file type is .DAT. 

#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol in 
apostrophes. 


Note that you cannot include a comment that begins with a 
semicolon (;comment) in an .OPEN statement. Doing so results in 
a syntax error. (Comments that begin with an exclamation mark 
('comment) are accepted.) 
Example 

sOPEN -SECOUT 


This directive opens the file SECOUT.DAT as an output file. 


-OPENA - OPEN SECONDARY FILE FOR APPEND 


4.36 .OPENA - OPEN SECONDARY FILE FOR APPEND 


The .OPENA directive opens a secondary file and appends all 
subsequent data to the file. 


Format (brackets not part of syntax) 
.OPENA [#n] filename 
where: 


filename A secondary file to be opened with subsequent data 
appended to it. The default file type is .DAT. 


#n An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol in 
apostrophes. 


Note that you cannot include a comment that begins with a 
semicolon (;comment) in an .OPENA statement. Doing so results in 


a syntax error. (Comments that begin with an exclamation mark 
(!comment) are accepted.) 


If the specified file does not already exist, .OPENA becomes’ the 
.OPEN directive by default. 


Example 
.OPENA SECOUT 


This directive opens the file SECOUT.DAT as an output file and 
appends subsequent data to it. 


-OPENR - OPEN FILE FOR READING 


4.37 .OPENR - OPEN FILE FOR READING 
The .OPENR directive opens a file for reading with the .READ 
directive. 
Format (brackets not part of syntax) 
-OPENR [#n] filename 
where: 


filename A file to be opened for reading. The default file 
type is .DAT. 


#N An optional file number in the range 0 to 3. The 
default is #0. You can substitute a numeric 
symbol for the value n by enclosing the symbol in 
apostrophes. 


You cannot include a comment that begins with a_ semicolon 


(;comment) in an .OPENR statement; it results in a syntax error. 
(Comments beginning with an exclamation mark (!comment) are 
accepted.) 

Examples 


~OPENR INDADD 


This directive opens the file INDADD.DAT for reading with the 
».READ directive. 


.OPENR DATLIB.ULB/LB:DATINP 


This directive opens for reading the library module DATINP 
contained in the universal library DATLIB. 


-sPARSE: = PARSE STRINGS INTO SUBSTRINGS 


4.38 .PARSE - PARSE STRINGS INTO SUBSTRINGS 


The .PARSE directive parses strings in a command line into 
substrings. 


Format 
-PARSE <string> <control-string> <varl> <var2> ... <var9> 


The string is broken up into substrings as specified by the 
control string. The substrings are stored in the specified 
variables. The first character of the control string delimits 
the first substring, the second character of the control string 
delimits the second substring, and so on. The last character of 
the control string is repeated if the number of variables exceeds 


the length of the control string. If you specify more variables 
than substrings, the additional variables are set to null 
strings. If you specify fewer variables than the number of 


substrings that can be parsed, the last variable contains the 
unparsed fragment of <string>. 


The symbol <STRLEN> contains the actual number of substrings that 
Indirect processed (including explicit null substrings). 


Example 
.PARSE COMMAN " ," FILE Al A2 A3 A4 A5 
Given that COMMAN contains MTESTELLE IND; DC. b0A" ; this 


directive has the following results: 


FILE = TESTFILE 


Al = IND 
A2 = DEL 
A3 =" Or 
A4 = LOA 
Ad =~ iL | 


<STRLEN> contains a 5. 


»~PAUSE - PAUSE FOR OPERATOR ACTION 


4.39 .PAUSE - PAUSE FOR OPERATOR ACTION 


.PAUSE is provided for compatibility with RSX Indirect. It is a 
no-op under the PRO/Tool Kit. 
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-READ - READ NEXT RECORD 


- READ NEXT RECORD 


The .READ directive reads the next record into a specified string 


variable. 


the record is longer than 


occurs. 


After every .READ operation, 
file 
reflects whether an end-of-file was 
Tf an error or end-of-file occurs, 


the FCS-11 


does not 


clear 


record is written i 
132 (decimal) c 


entire 


the special sym 
code for the read and the 
Found. 

<EOF>.) 


nto the variable. If 
haracters, an error 


bol <FILERR> contains 
Special symbol <EOF> 


string variable remains unchanged from its previous state. 


Format (brackets not part of syntax) 


» READ 
where: 


#n 


SSSSSS 


Example 


- LOOP: 


.ERROR* 


. DONE: 


SSSSSS 


An optional file number that 


from which the record is 
number must be one of the 
previous .OPENR- statement. 


You can substitute a numeric 
n by enclosing the symbol in 


(Note that .OPENR 
the 

specifies the file 
to be read. The file 


numbers used in a 
The default is #0. 

symbol for the value 

apostrophes. 


The string variable into which the record will be 


read. 


.ENABLE SUBSTITUTION 


~OPENR FILE 


IF <FILERR> NE 1 .GOTO ERROR 


-READ RECORD 


.IFT <EOF> .GOTO DONE 

IF <FILERR> NE 1 .GOTO ERROR 
;. *RECORD: 

.GOTO LOOP 

. CLOSE 
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~READ - READ NEXT RECORD 


These directives open the file FILE.DAT for reading, read each 
record into the string variable RECORD, display each record on 
the terminal screen, and close the file. 


~RETURN ~ RETURN FROM A SUBROUTINE 


4.41 .RETURN - RETURN FROM A SUBROUTINE 


The .RETURN directive signifies the end of a subroutine and 
returns control to the line immediately following the .GOSUB 
directive that initiated the subroutine. 


Format 


- RETURN 


.SETT/.SETF/.SETL - SET SYMBOL TO TRUE OR FALSE 
4.42 .SETT/.SETF/.SETL - SET SYMBOL TO TRUE OR FALSE 


The .SETT, .SETF, and .SETL directives define or change the value 
of a specified logical symbol. If the symbol has not been 
defined, Indirect makes an entry in the symbol table and sets the 
logical symbol to the value specified. If the symbol has already 
been defined, Indirect resets the symbol accordingly. Indirect 
exits with a fatal error if the logical symbol was defined 
previously aS a numeric or string symbol. 


Formats 
“poe. SSSSSS 
~SETE SSSSSS 


-SETL ssssss llllll 


where: 

SSSSSS The i1- to 6-character logical symbol to be 
assigned a true or false value. 

i a I A logical or numeric expression. SSSSSS is 
assigned the value of 111111 when the logical 
expression is evaluated. 

Examples 


-oETT xX 

This directive sets the logical symbol X to true. 
~SETF ABCDE 

This directive sets the logical symbol ABCDE to false. 
-SETL TEST SWITCHA!SWITCHB 


This directive sets the logical symbol TEST to true if SWITCHA or 
SWITCHB is true. 


~SETN - SET SYMBOL TO NUMERIC VALUE 


4.43 .SETN - SET SYMBOL TO NUMERIC VALUE 


The .SETN directive defines or changes the value of a specified 


numeric symbol. If the symbol has not been defined, Indirect 
makes an entry in the symbol table and sets the symbol to the 
numeric value specified. If the symbol has already been defined, 


Indirect resets the symbol accordingly. Indirect exits with a 
fatal error if the numeric symbol was previously defined as a 
logical or string symbol. 


Format 

-OETN ssssss numexp 
where: 

SSSSSS The 1- to 6-character numeric symbol. 

numexp A numeric expression. 
When specifying a numeric value to assign to a symbol, you may 
combine a numeric symbol or constant with another numeric symbol 
or constant to form a numeric expression. If numeric expressions 
are used, no embedded blanks or tabs are permitted. Evaluation 
is done from left to right unless parentheses are used to form 
subexpressions that are evaluated first. The radix of an 


expression is octal if all the operands are octal and decimal 
mode has not been enabled; otherwise the radix is decimal. 


Examples 
.SETN NUMBER 27 


This directive assigns to the numeric symbol NUMBER the value 27 
(octal). 


.SETN Al 3*(A2-5) 


This directive assigns the numeric symbol Al the value of symbol 
AZ minus 5 multiplied by 3: 


~-SETO/.SETD - SET SYMBOL TO OCTAL OR DECIMAL 


4.44 .SETO/.SETD - SET SYMBOL TO OCTAL OR DECIMAL 


The .SETO and .SETD directives redefine the radix of a specified 
numeric symbol (without affecting the symbol’s actual value). 


If the symbol has not been defined, Indirect makes an entry in 
the symbol table and sets the symbol to the specified radix with 
a value of 0. If the symbol has already been defined, Indirect 
resets the symbol accordingly. Indirect exits with a fatal error 
if the symbol was previously defined as a logical or _ string 
symbol. 


Formats 
-OETO sSSSSS 


-SETD ssssss 


where: 
SSSSSS The 1- to 6-character numeric symbol to be 
assigned an octal or decimal radix. 
Example 
.SETN A 10 ; Sets symbol A to 10 (octal) 
-SETD A ; Defines A as a decimal radix symbol with a 
value of 8 (decimal). 
-SETO A ; Defines A back to original radix with a 


value of 10 (octal). 


.SETS - SET SYMBOL TO STRING VALUE 
4.45 .SETS - SET SYMBOL TO STRING VALUE 


The .SETS directive defines or changes the String value of a 
specified string symbol. If the symbol has not been defined, 
Indirect makes an entry in the symbol table and sets the symbol 
to the specified string value. If the symbol has been defined, 
Indirect resets the symbol accordingly. Indirect exits with a 
fatal error if the symbol was defined previously as a logical or 
numeric symbol. 
Format 

so LS. 6SsSsss “Strexp 
where: 

SSSSSS The i- to 6-character string symbol. 

strexp Any string expression. 
Indirect assigns to the specified symbol the string value 
represented by the string expression strexp. If a string 
constant is used in strexp, the constant must be enclosed by 
quotation marks ("constant"). 
You can combine a string symbol, constant, or substring with 
another string symbol or substring by the string concatenation 
operator (+) to .fOrm a string expression. 
Examples 

-SETS A "ABCDEF" 


This directive assigns to the string symbol A the string value 
ABCDEF. 


<SU7S. .GTRA. "224. 
This directive assigns string symbol STR2 the value Z22Z. 
SETS X STR2+"ABC" 


This directive assigns string symbol X the value of symbol STR2 
plus ABC (that 1S ZZZABC). 


.SETS X STR2+A[1:3] 
This directive is equivalent to the previous directive; it 


assigns the string symbol xX the string value of STR2 plus the 
First three characters of string A (that is ZZZABC). 
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-oETS - SET SYMBOL TO STRING VALUE 


The substring select expression is of the forn: 


"([start-index:ending-index]". 


soulo MYFILE <DIRECT>S+'MYFILE TXT" 


This directive assigns the string symbol MYFILE the string value 
of the current directory and the string contained within the 
quotation marks. For example; 1af- the current “directory -is 
[USERFILES], then MYFILE is assigned the string 


value 
[USERFILES ]MYFILE.TXT. 


.STOP - TERMINATE COMMAND FILE PROCESSING 


4.46 .STOP - TERMINATE COMMAND FILE PROCESSING 


The .STOP directive immediately terminates command file 
processing and exits. The message 
$ @ <EOF> 


is then displayed (unless .DISABLE DISPLAY is in effect). 


The .STOP directive allows you to optionally set the exit status 
for Indirect execution. 


Format (brackets not part of syntax) 


-STOP [value] 


where: 
value An optional numeric expression to serve as_ the 
exit status for Indirect. If you do not specify 
an exit status value, the .STOP directive 1s 
identical to the logical end-of-file directive 
(/). 
Example 
-STOP Q 


This directive terminates command file processing and sets the 
exit status for Indirect to Q. 


-TEST - TEST SYMBOL 


4.47 .TEST - TEST SYMBOL 


The .TEST directive has two different functions. It tests a 
variable and sets various special symbols accordingly, and it 
does substring searches and sets the special symbol <STRLEN> 
accordingly. 
Format 1 
-TEST SSSSSS 
where: 
SSSSS The 1- to 6-character symbol to be tested. 
The results of the test are as follows: 
® If variable is a string, <SYMTYP> is set to 4 and 
<STRLEN> contains the length of the string. Also, the 
Special symbols <ALPHAN>, <NUMBER>, <RAD50>, and <OCTAL> 
are set based on a scan of the characters of variable. 


® If variable is numeric, <SYMTYP> is set to 2. 


® If variable is octal, <SYMTYP> is set to 2 and <OCTAL> 
is set to TRUE. 


@® If variable is logical, <SYMTYP> is set to 0. 
Format 2 
.TEST string substring 
where: 
string A string symbol ae constant. 
substring A string expression. 
In this case, the substring is searched for in the specified 
Slring: If the substring is present, <STRLEN> is set to the 


position of the starting character of the substring within the 
string. If substring is not present, <STRLEN> is set to 0. 


~TEol = VEST SYMBOL 


Examples 
1. If SUM is a string symbol, the directive statement: 
~lhSl SUM 


sets <SYMTYP> to 4 and places the number of characters 
represented by the symbol SUM into <STRLEN>. 


2. The directive statements: 


-SETS MAIN "ABCDEF" 
-TEST MAIN "Cc" 


set <STRLEN> to 3, C’s position in string ABCDEF. 


st EOTDEVLILCE = “TEST DEVICE 


4.48 .TESTDEVICE - TEST DEVICE 


The .TESTDEVICE directive allows a command file to acquire 
information about any device in the system. The information, 
including error indications, is contained in the string symbol 


<EXSTRI>.. Each device attribute in the string is separated by a 
comma (which allows processing by the . PARSE and stES? 
directives). The first field of the string is the full physical 
name of the device. The next four fields are octat 
representations of the device-characteristics words (U.CW1 
through U.CW4 of the Unit Control Block). Additional fields 


contain more information about the device. 
Format 

-TESTDEVICE dd[nn]: 
where: 


dd ian: The device about which the command file is 
requesting information. 


The information stored in <EXSTRI> is in the following form: 


Gdns pkey es kK eR Ar a. ce pacr, 
where: 
ddnn: The physical device name for the device specified 


in the command line. 


xx xx, The four device-characteristics words in octal 
Oo oreo ¢ notation. 
atr One or more of the following device attributes: 
NSD "No such device" is configured into this 
system. 


LOD The device driver is loaded. 
UNL The device driver is not loaded. 


Example 
STESTDEVICE: Sys 


This directive acquires information about user logical device SY: 
and stores it in <EXSTRI>. 


.TESTFILE - TEST A FILE 
4.49 .TESTFILE - TEST A FILE 


The .TESTFILE directive determines if a specified file exists. 


If you specify a file in the command line, the results of a 
-TESTFILE operation are contained in the symbols <FILSPC> and 
<FILERR>. <FILSPC> contains the fully qualified file 


specification and <FILERR> contains the FCS status code resulting 
From the search for the file. 


Formats 
-TESTFILE filespec 
where: 
filespec Is the file to be tested. 
Examples 
;TESTEFIGE IND.aMAP 
This directive assigns the following values if the file exists: 


<FILERR> : 
<FILSPC> = DW1:[USERFILES]IND.MAP; 4 


If the file does not exist, the directive assigns the following 
values: 


<FILERR> = 230. 
<FILSPC> = DW1:[USERFILES]IND.MAP;0 
The following directive translates the logical name TI: into its 


physical device name. 
MDLEST PILE “Ls 
The directive assigns the symbol values as follows: 


1 
TV. DAT? 0 


<FILERR> 
<FibSaPe> 


~TESTPARTITION - TEST A PARTITION 


4.50 .TESTPARTITION - TEST A PARTITION 


The .TESTPARTITION directive allows a command file to obtain 
information about a partition in the system. The partition can 
be the one in which Indirect is running or any other partition. 
You can use the directive to verify that a partition is large 
enough before installing a task in it or that the partition is 
present before loading a special system. Indirect returns the 
information (in the special symbol <EXSTRI>) in the following 
format: 


partition-name,base,size,type, 
where base and size are in 64-byte blocks and type is SyYS_ for 
system-controlled partitions, USR for user-controlled partitions, 
Or NSP for an unknown partition name. If the partition is not 
found, Indirect returns a "No Such Partition™ error in the form: 
partition-name,,,NSP, 
Format 
.TESTPARTITION partition-name 


where: 


partition- A 1- to 6-character legal partition name. 
name 


Example 


«Leo UPARTITION GEN 
PGENS 250072303 ;;5% 5, 


This directive obtains information about the partition named GEN. 
The partition has a starting address of 150000 (octal), is 230300 
(octal) bytes long, and is a system-controlled partition. 


pTEOT SVS TEM. =PBoL: Ys eM 


4.51 .TESTSYSTEM - TEST SYSTEM 


The .TESTSYSTEM directive allows a command file to acquire 
information about the presence of certain operating system 
features. 


Format 
-TESTSYSTEM keyword number 
where: 


keyword identifies the system component to be returned. 
Valid keywords are: 


OPTION which interprets the immediately 
following symbol (number) as a number 
indicating the system feature to be 
interrogated. 


SERIAL which returns’ the processor serial 
number in the <EXSTRI> return string 
value. 


number is a number representing the desired feature. 
(Symbolic equivalents for these numbers, called 
system feature symbols, are listed in the P/OS 
System Reference Manual under the description of 
the FEATS system directive.) For convenience, 
the command l¢brary -LUNDSYS.CLB. ‘contains a 
procedure (INDSFN) Enae performs Feature 
testing. The return value of string <EXSTRI> is 
the string. “<TRUE>* «or "“<FALSE>",, depending upon 
whether or not the current system contains or 
was built with the indicated feature. 


Example 


@DW1:[1,2]INDSYS/LB:INDSFN HFSFPP ! is FPP present? 
.SETL FPUPRS '<EXSTRI>’ 


Sets the logical symbol FPUPRS to true or false, depending on 
whether or not the floating point chip is installed on this 
system. HFSFPP is a system feature symbol. 


-TESTSYSTEM OPTION =16.. 
-vGli: PPUPRS. * <BXSTRID>’ 


sTESTSYSTEM =. TEST SYSTEM 


Does the same as the previous example, except that it uses’ the 
actual number representing the FPP (-16.) rather than the system 
feature symbol (HFSFPP). 


. TRANSLATE - TRANSLATE A LOGICAL NAME 

4.52 .TRANSLATE - TRANSLATE A LOGICAL NAME 
This directive attempts to translate a logical name as defined by 
the DCL command ASSIGN. 
Format 

.TRANSLATE logical-name 
If available, the translated value of ’logical-name’ is returned 
in <EXSTRI>. The logical-name must have been previously defined 
(using the ASSIGN command, for example). 
The .TRANSLATE command will translate a logical name by first 
searching in the USER logical name table. If the logical name is 
not found, the SESSION logical name table is’ searched. If the 
logical is still not found the SYSTEM table is searched. 


NOTE 
You cannot limit the search to a particular table 
as. “YOu can im: DCL. 


Example 


The directive: 


.TRANSLATE LDWOO1: 
7’ <EXSTRI>D’ 


displays the following: 


;BIGDISK 
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~WAIT - WAIT FOR A TASK TO FINISH EXECUTION 


4.53 .WAIT - WAIT FOR A TASK TO FINISH EXECUTION 


.WAIT is provided for compatibility with command files moved from 
RSX-11 systems. It is a no-op under the PRO/Tool Kit. 


4-91 


-XOQT - INITIATE PARALLEL TASK EXECUTION 


4.54 .XQT - INITIATE PARALLEL TASK EXECUTION 


-XQT 1s provided for compatibility with command files transferred 
from RSX-11 systems. The remainder of the command line is passed 
to DCL as though the ".xXQT" had not been present. 


COMPATIBILITY WITH COMMAND FILES FROM RSX SYSTEMS 


4.55 COMPATIBILITY WITH COMMAND FILES FROM RSX SYSTEMS 


Many features of the indirect command processors present on 
RSX-11M and RSX-11M-PLUS has been preserved under the PRO/Tool 
Kit. Because of differences in the goals of the P/OS' system, 
some commands and symbols have little or no meaning. For 
example: 


o The .WAIT and .XQT commands are present and parsed but behave 
as no-operation commands. 


o The .XQT command is implemented as a synchronous operation, 
Since it is not possible to initiate multiple commands or 
programs for parallel execution. 


o The .PAUSE command does not pause. Command file processing 
continues without delay. 


The following special symbols are available in the symbol table 
of the PRO/Tool Kit INDIRECT. When transporting procedures from 
other RSX-11 systems that make use of these symbols, examine such 
usage and make any appropriate changes. 


<ALTMOD> use: <ESCAPE> 

<BASLIN> always <FALSE> 

<CONFIG> see module INDCFG in the procedure 

<ERRCTL> behave as on RSX-11 systems 

<ERRNUM> behave as on RSX-11 systems 

<ERRSEV> behave as on RSX-11 systems 

<FILATR> as on RSX-11 systems 

<FMASK> see module INDSFN 
in library LB000:[{1,2]INDSYS.CLB. 

<IAS> always <FALSE> 

<LIBUIC> not meaningful 

<LOCAL> always <TRUE> 

<MAPPED> always <TRUE> 

<NETUIC> not meaningful 

<NXTSYM> use module INDDMP in LBO0O00:[{1,2]INDSYS.CLB 

<RSALLD> Always false in RSX-11M/M-PLUS and P/OS 
systems 

<SYSUIC> not meaningful 

<TISPED> always 0 on TT1: 


INDIRECT MESSAGES 


4.56 INDIRECT MESSAGES 


When Indirect encounters an error, it prints the appropriate 
error message and the command line in which the error occurred. 


If the line contained a substitution, the line as it 
before the substitution took place is also displayed. 


4.56.1 Information-Only Messages 
@ <EOF> 
Indirect has reached the end-of-file for the 


command file and is terminating execution. 


END: == CONTINUING 


appeared 


outermost 


Indirect is resuming execution after a .PAUSE or .DELAY 


directive. 


IND. <== DELAYING 


A .DELAY directive was just executed, halting the 
processing of an indirect command file for a specified 


period of time. 


IND = INVALID ANSWER OR TERMINATOR 


In response to a question from .ASK, you 


entered 


something other than Y, N, or null, followed by a 


RETURN; or you did not enter a numeric 


value in 


response to an .ASKN question; or you pressed the 


<ESCAPE> key either without escape recognition 


enabled 


or as a character other than the first one following 


the question. The question will be repeated. 


IND 


INDIRECT MESSAGES 


VALUE NOT IN RANGE 


The response to an .ASKN or  .ASKS question was not 
within the specified range. Indirect repeats the 
question. 


4.56.2 Error Messages 


IND 


IND 


IND 


IND 


IND 


IND 


BAD RANGE OR DEFAULT SPECIFICATION 

An illegal character was specified as a range or 
default argument. Only numeric expressions are 
permitted. 

COMMAND FILE OPEN ERROR 

The file being invoked in an @file or @file/LB:module 
command line cannot be found or opened. 

DATA FILE ERROR, CODE x. 

Indirect encountered an error while processing an 
JOPEN } .OPENA, .CLOSE, or  .DATA directive or a data 
mode access to the secondary file. 

FILE ALREADY OPEN 

An .OPEN or .OPENA directive specified a file that was 
already open. 

FILE NOT FOUND 

An @filename or .CHAIN directive specified an incorrect 
file name or nonexistent file. 


FILE NOT OPEN 


Indirect encountered a .DATA or .CLOSE directive that 
did not reference an open file. 
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IND 


IND 


IND 


IND 
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FILE READ ERROR 


An error was detected in reading the indirect command 
file. This error is usually caused by records that are 
more than 132 (decimal) bytes long. 


ILLEGAL FILE NUMBER 
The file number in an  .OPEN, .OPENA, .OPENR, .DATA, 


-ENABLE DATA, .READ, or .CLOSE directive is not in the 
range -of UW through: 3:. 


ILLEGAL NESTING 

Too many Begin-End blocks have been nested in the 
indirect command file. The maximum nesting depth is 
limited to the size of the symbol table. 

INITIALIZATION ERROR, CODE x. 

Indirect failed to complete initialization when you 
invoked it. The following list gives the meaning of 


the displayed code number: 


1. Unable to acquire system information such as 
the UIC or device name. 


2. Impure area setup failed. 
3. Unable to acquire task-specific information. 
4. Unable to acquire terminal-type information. 


5. Unable to acquire the disk name and other 
information about the system device (SY:). 


6. Unable to allocate enough space for command 
and data T/O buffers. The EXTEND TASK 
directive failed to return sufficient space 
for Indirect to allocate the buffers. 


7's Initialization of allocated buffers failed. 


8. Initialization of the DATA file structures 
failed. 


9. Allocation of FCS-11 buffers for data and 
command lines failed. 
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10. Symbol table initialization failed. 
iis Initialization. cleanup failed. 
12. Unable to obtain initial command line. 


13. Unable to initialize the FMS-11 forms driver 
impure area. 


>13. jError codes greater than 13 are returned by 


special purpose initialization modules. 


Error number 6 is the only initialization error that 
you should encounter. If any other error from i 
through 12 persists, call your DIGITAL Customer Support 
Center, 

INVALID KEYWORD 

An unrecognized keyword (preceded by a period) was 
specified. 

LABEL NOT AT BEGINNING OF LINE 

The specified label does not start in the first column 
of the line. All labels must do so. 

MAXIMUM INDIRECT FILE DEPTH EXCEEDED 

An attempt was made to reference an indirect command 
file at a nested depth greater than the maximum 
specified in the build file for the Indirect task. 

NO POOL SPACE 

The executive dynamic memory allocation has been 
exhausted. 

NULL CONTROL STRING 

The control string specified with the .PARSE directive 


was Muck | (there were no characters between the 
quotation marks). 
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NUMERIC UNDER- OR OVERFLOW 


The evaluation of a numeric expression yielded a value 
outside the range 0 through 177777 (octal). 


REDEFINING A READ-ONLY SYMBOL 


An attempt was made to assign a new value to a 
read-only symbol. Read-only symbols cannot be 
overwritten. 


REDEFINING SYMBOL TO DIFFERENT TYPE sSSSSSS 


An .ASK, .ASKN, -ASKS, «READ, Pig oi ba ba Poy sre te oe -oblL;y 
-SETN, or .SETS directive was used in an attempt to set 
the specified, already defined symbol to a different 
type. The first definition of a symbol determines its 
type (logical, numeric, or string); subsequent value 
assignments must conform to the original type. 


»-RETURN WITHOUT .GOSUB 

A .RETURN directive was specified without a previous 
call to a subroutine (.GOSUB). 

STRING EXPRESSION LARGER THAN 132. BYTES 

An attempt was made to generate a string expression 
longer than 132 (decimal) characters. 

STRING SUBSTITUTION ERROR 

Indirect encountered an error during a substitution 
operation. A probable cause for the error is either 
the omission of a second apostrophe or the 
specification ofa symbol that 1s not defined. 
SUBROUTINE NESTING TOO DEEP 

The maximum subroutine nesting level was exceeded. The 


maximum level is specified in the build file for the 
Indirect task. 


IND 


IND 


IND 


IND 


IND 


INDIRECT MESSAGES 


SYMBOL TABLE OVERFLOW SSSSSS 

The symbol table was full and there was no space _ for 
symbol ssssss. 

SYMBOL TYPE ERROR SSSSSS 

The symbol ssssss was used out of context for its type; 
for example, a numeric expression referenced a logical 
symbol. Only symbols of the same type can be compared. 


SYNTAX ERROR 


The format of the specified command line is incorrect. 


UNDEFINED LABEL .label: 

The label .label: specified in a .GOTO, .GOSUB, or 
-ONERR directive could not be found. 

UNDEFINED SYMBOL SSSSSS 


The symbol ssssss was referenced, but it had not’ been 
defined. 


CHAPTER 5 
FILE COMPARE UTILITY (CMP) 


The File Compare Utility (CMP) compares the contents of two ASCII 
files on a line-by-line basis, determining whether parallel 
records are identical. The utility produces a listing of the 
differences between the two files. 


Using CMP, you can perform the following file-compare functions: 


® Generate a listing showing the differences between the two 


files. Each difference is listed as a pair: first, the 
lines from the first file, then the lines from the second 
file. 


@ Generate a listing in the form of one list, with differences 
marked by change bars. 


@© Generate output suitable for input to the Source Language 


Input Program utility (SLP). This output contains the SLP 
commands and input required to make the first input file 
identical to the second input file. (For more information on 


SLP, see Chapter 10.) 


CMP provides switches that allow you to eontrot compare 
processing. Using these switches, you can control the comparison 
of blanks, tabs, form feeds, and comments. You can also control 


line numbering and specify the number of lines required for CMP 
to consider that a match has been made between lines in the two 
files. 


OI 
1 
}— 


INVOKING CMP 


5.1 INVOKING CMP 


You can invoke CMP in two ways: 


1. Invoke the DIFFERENCES command, which in turn invokes CMP. 
See Chapter 3 for a description of the DIFFERENCES command. 


2. Invoke CMP directly from the DCL command level. 


To invoke CMP directly from the DCL command level, enter the 
following command: 


You receive a new prompt to indicate that you are in the CMP 
environment: 


CMP> 


Once you are in the CMP environment, CMP waits for your command. 
The following section describes the command format. 


5.2 CMP COMMAND FORMAT 

The format for a CMP command is: 
foutfile[/sw...J=] infilel,infile2 

outfile 


The file specification for the output file. This file can 
be in one of three formats, depending on the switch you 


specify in the command line. The defaults are: 
SYO User’s default system device 
Pewrd22*4 Current directory CMP is running under 
FILCOM Default file name 
sot Default file type 


However, if you do not specify an output file, the output 
defaults to your terminal screen. For example: 


CMP>FILE1.MAC,FILE2.MAC 


CMP COMMAND FORMAT 


CMP lists the differences between FILE1.MAC and FILE2.MAC on 


your terminal screen. If you type the equal sign but give 
no output file specification, only the total number of 
differences is output to your terminal screen. For example: 


CMPS=S=F PLELcaMACs 1. PI Le2. MAC si 
10 differences found 


[SWeee 


Switches that you apply to the output file specification. 
Some of the switches can be negated and some are mutually 
exclusive. See Section 5.3 for more information. 

infilel 
The file specification for the input file to be compared to 
infile2. The file name of this file must be specified. The 
default file type is .MAC. 


infile2 


The file specification for the input file to be compared to 


Patel You do not have to have a complete file 
specification. The specifications for infilel are used as 
defaults for any unspecified portions of infile2. For 
example: 


CMPS D412] FOO )EXEC; #2 
CMP interprets the second input file as DZ1:[FOO]EXEC.MAC;2. 


If you do not specify a file version number, the default 1s the 
most recent version of the file. 


5.3 CMP SWITCHES 


This section lists the CMP switches, describes the function of 
each one, and gives the default setting for each one. You 
specify switches after the output file in the command line. 


/BL Specifies that blank lines in both files be included in 
/-BL compare processing. If this switch is specified in the 
form /-BL, blank lines are not included in compare 


processing. /-BL is the default switch. 


/CB 
J HES 


/CO 
p20 


/DI 
Jot 


/FF 
/-FF 


/uLiin 


/ LN 
/~-LN 


/MB 
/-MB 


fst 


au. | 


CMP SWLTCHES 


Specifies that CMP list infile2 with change bars, in 
the form of exclamation marks (!), to denote which 
lines do not have a corresponding line in infilel. 
When a section of lines in infilel has been deleted in 
infile2 (the output listing file), the first line not 
deleted is marked. /-CB is the default switch. 


You can change the change bar character from _ the 
exclamation mark to any character you wish by means of 
the /VB switch. 


Specifies that CMP include comments (that is, text 
preceded by a semicolon) in compare processing. /CO is 
the default switch. 


Specifies that CMP list the differences between the two 
Files (rather than marking the lines in infile2). JOI 
is the default switch. 


/CB and /DI are mutually exclusive switches. If you 
specify both, /CB overrides /DI. 


Specifies that CMP include records consisting of a 
Single form-feed character in compare processing. /-FF 
is the default switch. 


Specifies that a number (n) of lines must be identical 
before CMP recognizes amatch. /LI:3 is the default 
Switch. 


When it encounters a match, CMP lists all the preceding 
nonmatching lines, along with the first line of the 
matched sequence of lines to help you find the location 
in the file where the match occurred. 


Specifies that lines in the output file be preceded by 


their line number. Line numbers are incremented by one 
for each record read, including blank lines. /LN is 
the default switch. Le vow  Specriy 7sb,. ~EN 2s 


unnecessary. 


Specifies that CMP include all blank and tab characters 


in a line in compare processing. If you specify /-MB, 
CMP interprets any sequence of blank and/or’ tab 
characters as a Single blank character. However, all 


Spaces and tabs are printed in the output listing. /MB 
is the default switch. 


Directs CMP to generate an output file suitable for use 
as SLP command input. When you specify /SL, CMP 
generates the SLP command input necessary to make 


O1 
I 
i 


/TB 
/-TB 


/VB:nnn 


CMP defaul 


Table 5-1: 


CMP SWITCHES 


infilel identical to infile2. If a 1- to 8-character 
alphanumeric symbol is included after the /SL switch 
(:au), an audit trail is specified for SLP input. 
Section 5.4.3 gives an example of how CMP generates SLP 
command input. (For information on SLP, see Chapter 
10.) /-SL is the default switch. 


Specifies that CMP include all trailing blanks on a 
line in compare processing. If you specify /-TB, CMP 


ignores all blanks following the last nonblank 
character on a line. When you specify /-CO and /-TB 
together, blanks that precede a semicolon (;) are 


considered trailing blanks and are ignored. /TB is the 
default switch. 


Specifies an octal character code for the character you 
want to use aS a change bar. You use this switch with 
the /CB switch. The value nnn specifies the octal 
Character’ code. For example, you can specify /VB:174 
for a vertical bar. /VB:041 (for an exclamation mark) 
is the default switch. 


t switch settings are listed in Table 5-1. 


Summary of CMP Default Switch Settings 


Default Description 


/-BL 
/-CB 
/CO 
/DI 
/-FF 


FLAS 


/ UN 
/MB 


Poo 


Do not compare blanks. 

Do not generate change bars. 

Compare comments. 

List only the differences between the two files. 
Do not compare form-feed characters. 


Find three identical lines before a match can 
occur. 


Generate numbered lines. 
Compare all blank and tab characters. 
Do not generate an output file suitable for use as 


SLP command input. 


a= 5 


CMP SWITCHES 


Default Description 
/TB Compare all trailing blanks. 


/VB: 041 Set the exclamation mark (ASCII 041) as the change 
bar character. Used with /CB. 


5.4 FORMATS OF CMP OUTPUT FILES 


CMP uses the two input files you specify on the command line to 
create an output file. CMP compares each line in infilel to its 
Sequential. counterpart in. intite2. When ‘there -are -dirtterences 
between the two files, CMP displays those differences in one of 
three output formats: 


@® Differences format (default) (/DI) 
@ Change bar format (/CB) 
e@ SLP command input format (/SL) 
This section gives an example of each of these formats. In the 


examples in the subsequent sections, the following files are used 
as anfilel (TESTI.ADAT?1) cand Aantile2? (TESTZ.DAT;1)< 


DW1: [USERFILES ]TEST1.DAT;1 DW1i: [USERFILES ]TEST2.DAT;1 


LINE1 EINE 
LINE2 LINE2 
LINE3 LINE3 
LINE4 LINE4 
LINES LINES 
12345 45678 
23456 56739 
34567 67891 
LINEQ LINE9 
LINE10 LINE1O 
LINE11 LINE11 
EXTRA EXTRA 
EXTRA 
EXTRA 
EXTRA 


FORMATS OF CMP OUTPUT FILES 


5.4.1 Differences Format 


If you enter a command line and do not specify any switches, CMP 
lists the differences between the two files on your terminal 
screen or in an output file. The differences are listed in 
pairs; Cirsc, the lines from infilel that do not have 
counterparts in infile2 are listed, then the lines from infile2 
that do not have counterparts in infilel are listed. Each set of 
lines is terminated by the first line (or set of lines) for which 
a match is successful. 


The following example shows the format of output generated 
without any switches. The output file is generated with the CMP 


command: 


CMP>TESTDIF.DAT=TEST1.DAT,TEST2.DAT 


KREEKKKEKEKKKKKRKEKRKKEKKRKEKRKRKRKEKR KKK KKK KKK KKKKSE 


i DW1:[USERFILES]TEST1.DAT;1 
6 LZ345 
7 23656 
8 3456.7 
9 LINEQ 
KRKEKEKKKKEKEKEKKKKKKKK 
2) DW1:[USERFILES ]TEST2.DAT;1 
6 45678 
7 56789 
8 67891 
9 LINEQ 
KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKK KKKAKKAKRKKKEHE 
13 DW1:[USERFILES ]TEST1.DAT;1 
KEEKKKKEKKKAKKKKKKEE 
2) DW1:[USERFILES]TEST2.DAT;1 


13 EATRA 
14 EXTRA 
Abe EATRA 


2 differences found 


The input files are TEST1.DAT and TEST2.DAT, which are shown in 
Section 5.4. There are two sets of differences separated by a 
long line of asterisks. (When there are several sets of 
differences, CMP separates each set from the next set by a long 
line of asterisks.) The short line of asterisks separates the 
pair of differences that comprise the set. 


Note that because /LI:n was not specified, the number of lines 
required for a match defaults to 3. Thus, CMP found two 
differences. 


FORMATS “OF CMP OUTPUT FILES 


5.4.2 Change Bar Format 


You. use-tnhe- 7CB ‘switch to generate a listing -containing . change 
bars that show the differences between two files. In the CMP 
command line, infile2 is the listing you want generated. 


The following example shows the format of output with change bars 
applied to lines from two files that do not match line for line. 
The output file is generated with the CMP command: 


TRPCMTHATRP RAT /sCR—T7FP¢CMN1 NWaAT THRIAMI Nam 
CMPOTESTDIF.DAT/CB=TESTI .DAT,TEST2Z.DAT 


Notice that the change bar is applied to the first line of match 
(line 9). 


el LINE 

2 LINE2 

3 LINE3 

4 LINE4 

5 LINES 

6 ! 45678 

y 4 56789 

8! 67a01 

ae LINEY 
10 LINE10 
de EINE Da 
12 EXTRA 
io. 4 EXTRA 

14 ! EXTRA 
io EXTRA 


2 differences found 


5.4.3 SLP Command Input Format 


You use the /SL[:au] switch to generate a file containing records 
to be used as SLP command input. /SL directs CMP to generate the 
SLP edit command lines and input lines required to make infilel 
identical to infilez. 


After executing CMP, you execute SLP (CMP does not generate an 
SLP command line). For a complete description of the SLP 
utility, see Chapter 10 in this manual. 


FORMATS QF CMP OUTPUT FILES 


The following example shows the format of output generated using 
the /SL switch. The output file is generated with the CMP 
command: 


CMP>TESTDIF.DAT/SL: BLSOQOQ1=TEST1 .DAT,TEST2.DAT 


~6,8,/77BLS001/ 
45678 
56789 
67891 
-12,,/7;BLS001/ 
EXTRA 
EXTRA 
EXTRA 


a 


5.5 CMP MESSAGES 

This section lists the CMP messages, gives a brief description of 
the condition that causes each message, and suggests a response 
to the condition: 

CMP -- n differences found 


Explanation: CMP found n differences between the two files. 


User Actions: This is an informational message. 


CMP -- Command syntax error 


Explanation: CMP found an error in the command line syntax. 


User Actions: Check the syntax of the command line 
specification and reenter the command line using the correct 
SVHCaXx. 

CMP -- Error reading input file 


Explanation: An I/O error occurred while CMP was reading an 
LIVOWG. ft Les 


User Action: Reenter the command line. 


CMP MESSAGES 


CMP -- Error writing output file 


Explanations An I/O error occurred while CMP was writing 
the output file. 


User Action: The output device may be full or bad. Check 
this, then reenter the command line. 


CMP -- Illegal /LI value 


Explanations You specified a negative value for the number 
of lines required for a match. 


User Actions Reenter the command line with a legal value 
specified. 
CMP -- Illegal switch or switch value 


Explanations An illegal switch or switch value was entered 
in the command line. 


User Actions Reenter the command line using a legal switch 
or switch value. 


CMP -- Open failure on input file #1 
Explanations: CMP could not open the first input file. 
User Actions Check the file specification for the first 
input file and reenter the command line using the correct 
file specification. 

CMP -- Open failure on input file #2 


Explanation: CMP could not open the second input file. 


User Actions Check the file specification for the second 
input file and reenter the command line using the correct 
file specification. 


CMP -- Open failure on output file 
Explanation: CMP could not open the specified output file. 
User Action: Check the file speécriication for the -ourput 


file and reenter the command line uSing the correct file 
specification. 


CMP MESSAGES 


CMP -- Too many differences for available core 


Explanation: The files were too dissimilar for CMP to 
all the differences in memory. 


User Actions You cannot compare the two files. 


Eat 


CHAPTER 6 
FILE DUMP UTILITY (DMP) 


The File Dump Utility (DMP) enables you to examine the contents 
of a specific file or volume of files. You can format the output 
in ASCII, octal, decimal, hexadecimal, or Radix-50 form and dump 
it to any suitable output device, such as a printer, terminal 
Screen, or disk. 


You can dump the header and/or virtual blocks of a file or only 
the virtual records of a file. If you are dumping a volume, you 
can specify a range of logical blocks. DMP handles blocks of up 
to 256 (decimal) words in length. The maximum block size must 
not exceed this length. 


DMP operates in two basic modes: file mode and device mode. Use 
file mode to dump virtual records or virtual blocks; use device 
mode to dump logical blocks. 


File Mode In file mode, one input file 1s specified, 
and all or a specified range of virtual 
blocks are dumped. You can also dump all the 
virtual records of a specified file in this 
mode. The input device must be aéeFILES-11 
formatted disk. 


In file mode, you can specify that data be 
dumped one record or one block at a time. A 
virtual block or record refers to one _ block 
or record of data ina file. Virtual blocks 
and records are numbered sequentially from 1 
through n, where n is the total number of 
blocks or records in the file. Virtual block 
0 contains the header of the file. Use the 
/BL:n:m switch to dump virtual blocks and the 
/RC switch to dump virtual records. The /BL 
and /RC switches are mutually exclusive. 
(DMP switches are listed in Section 6.3.) 


Device Mode In device mode, you specify only 

device, and a specified range 
blocks is dumped. The /BL:n:m swi 
required parameter in this mode. 
A logical block refers to a physica 
block ‘on disks Logical blocks: ar 
from 0 to n-1, where n is the total 
logical blocks on the device. 


NOTE 


The volume must be mounted fore 


6.1 INVOKING DMP 


You can invoke DMP in two ways: 


1. Invoke the DUMP command, which in turn invokes 
Chapter 3 for a description of the DUMP command. 


2. Invoke DMP directly from the DCL command level. 


To invoke DMP directly from the DCL command level, 
following command: 


S RUN SDMP 


You receive a new prompt to indicate that you are in 
environment: 


DMP> 


Once you are in the DMP environment, DMP waits for your 
The following section describes the command format. 


6.2 DMP COMMAND FORMAT 


The format for a DMP command is: 


foutfilej[/sw][/sw...]=inspec[/swl]l[/sw...] 


the input 
of logical 
tch is a 


1 512-byte 
e numbered 
number of 


ign. 


DMP. see 


enter the 


the DMP 


command. 


DMP COMMAND FORMAT 


outfile 


Specifies the output file. If the output file name and file 
type are unspecified, DMP creates the file DMPFIL.DMP. TI: 
(terminal) is also an acceptable outfile specification. 


/3w 


Specifies one of the switches listed in Section 6.3. Unless 
otherwise indicated in a switch description, all switches 
can be applied either to the input file or to the output 
file with equal effect. DMP will allow multiple dumps ina 
Single command line. Therefore, any or all of the current 
format switches may be specified. Certain switches are 
mutually exclusive. For example, the /HX, /LW, and /WD 
Switches are mutually exclusive hexadecimal dump switches. 
The first one in the following order will be the only one 
executed: /LW, /WD, /HX. 


inspec 


Specifies the input device and file or input device only. 
In file mode, the equal sign and the input file name and 
file type are required because DMP does not provide a 
default for either of them. However, the input file version 
number defaults to the latest version and the device 
defaults to SY: and the current directory. 


In device mode, the equal sign and input device are required 
as is the /BL:n:m switch which specifies the range of 
logical blocks to be dumped. 


For a complete description of file specifications, see the Tool 
Kit User’s Guide. 


6.3 DMP SWITCHES 


DMP switch specifications consist of a slash (/) followed by a 
Switch name, optionally followed by a value. The value is 
separated from the switch by a colon (:). DMP functions -are 


implemented by the following switches: 


Default The default is a word mode octal dump. 


/AS 


/BA:n:m 


DMP SWITCHES 


Specifies that the data should be dumped 
one byte at a time in ASCII mode. The 
control characters (Q-37 octal) are 
printed as eight-bit characters consisting 
of a circumflex (°), followed by the 
alphabetic character corresponding to the 


Character code plus 100 octal. For 
example, bell (code 7 octal) is printed as 
“G (code 107 octal). Lowercase characters 


(140-177 octal) are printed as a percent 
Sign (%), followed by the corresponding 
uppercase character (character code minus 
40 octal), unless the /LC switch is 
Specitied:. DMP will also display the DEC 
Multinational Characters. 


NOTE 


The /AS and /OCT switches are 
mutually exclusive when dumping 
bytes. 


Specifies a 2-word base block address (the 
initial base address is 0,0), where nis 
the high-order base block address (octal), 
and mis the low-order base block address 


COC Gals). The address may also be 
Specified in decimal by using a period 
after the number. Ald future block 


numbers specified by the /BL switch will 
be added to this value to obtain an 


effective block number. This switch is 
useful for specifying block numbers that 
exceed 16 bits. For example: 


DMP>/BA:1:0 


specifies that all future block numbers 
will be relative to 65536 decimal (200000 
OCtdd)< 


DMP>/BA:0:0 


clears the base address. Once the /BA 
Switch is specified, it remains in effect 
until it 1s used again to set a new base 
address. 


/BL:n:m 


JODY 


JOG 


/¥Il:file-number: 


sequence-number 


JAD TEE OF 20] 


DMP SWITCHES 


When the /BA switch appears in a command 
line, no blocks are dumped. The only 
result of the command line is to set the 
base address. 


Specifies the range of blocks to be 
dumped, where nis the first block and m 
is the last block. The values of n and ao 
must not exceed 16 bits. In file mode 
only, the /BL switch is not required. If 
the /BL switch is not specified, DMP will 
dump all blocks of the specified file, 
relative to the current base address. 


If /BL:n:m is specified in file mode, it 
Specifies the range of virtual blocks to 
be dumped. If /BL:n:m is specified as 
/BL:0 in file mode, no virtual blocks are 
dumped. This is useful for dumping only 
the header portion of the file (see /HD). 
The /BL switch and the /RC switch are 
mutually exclusive. 


The /BL:n:m switch is a required parameter 
in device mode. When used in device mode, 
it specifies the range of logical blocks 
to be dumped. 


The value n represents the block number of 
the first block dumped. Successive blocks 
are labeled with a block number one higher 
than the preceding block number. The dump 
will continue until the block labeled m is 
dumped. 


Specifies that the data be dumped in octal 
byte format. 


Specifies that the data be dumped in 
decimal word format. 


In file mode, the file number can be used 
instead of a file name as a file 
Speciticarion. for anpuc. 


This switch is an optional parameter used 
in file mode. If specified, the /HD 
Switch causes the file header as well as 
the specified or implied portion of the 
file to be dumped. Example: 


Pac a 


/HX 


/ID 


/LB 


DMP SWITCHES 


DMP>TI:=JMF.DAT/HD/BL:5:6 


This example dumps the header of JMF.DAT 
in header format and virtual blocks 5 and 
6 in octal format. 


In addition, this switch has two options. 
ot cea the default, causes a FILES-11 
formatted dump of the header. a Oe 
Specifies an unformatted octal dump. An 
octal dump also occurs when DMP is used on 
non-FILES-11 headers. 


If you want only the header portion of the 
file to be dumped, specify: 


/HD/BL:0 


Specifies the format for data blocks that 
have the FILES-1i1 header structure. Other 
blocks are output as a data dump in the 
format selected by /AS, /BY, and so on, in 
default octal words. 


Example: 
DMP>HEAD.LST={[0,0]INDEXF.SYS/HF 


This example generates a dump of the index 
file INDEXF.SYS and formats all the 
headers in the file. 


Specifies that the data be dumped in 
hexadecimal byte format. Note that a 
hexadecimal dump reads from right to left. 
(See also the /LW and /WD switches.) 


Causes DMP’s version to be identified. 
This switch may be specified on a command 
line by itself at any time. 


Example: 


DMP>/ID 
DMP--DMP VERSION M0O7.1C 


Requests logical block information for a 
file. The starting block number and a 
contiguous or noncontiguous indication Lor 
the file are displayed. 


JC 


/LIM:n:m 


/ LW 


/MD[:n] 


ZOOL 


JR 


J RC 


DMP SWITCHES 


Example: 


DMP>TI*=RICKSFILE.DAT?3/LB 
STARTING BLOCK NUMBER = 0,135163 C 


The file RICKSFILE.DAT, version 3, is a 
contiguous file starting at block number 
Ory Oz (See /BA:n:m for block number 
description.) 


Specifies that the data should be dumped 
in lowercase characters. 


Specifies the range of bytes, n through no, 
of each record or block to be dumped. The 
default remains /OCT if you do not specify 
format switches. 


Specifies that the data be dumped in 
hexadecimal double-word format. 


Specifies a memory dump and allows control 


of line numbers. Line numbers are 
normally reset to zero whenever a block 
boundary 1s crossed. The /MD switch 


allows lines to be numbered sequentially 
for the full extent of the file, that is, 
the line numbers are not reset when block 
boundaries are crossed. The optional 
value (:n) specifies the value of the 
first line number. The default is 0. The 
/MD switch is used with the output file 
specification. 


Specifies that the data should be dumped 
in octal format in addition to other 
formats specified. If no> DMP format 
Switches are specified, the default is 
octal. The /AS switch and the /OCT switch 
are mutually exclusive when dumping bytes. 


Specifies that data be dumped in 
Radix-50-format words. | 


Specifies that data be dumped a record at 
a time (rather than a block at a time). 
The data format is determined by setting 
any of these format switches: /AS, /DC, 
JARs: Si y Roy: Or 7D 


DMP SWITCHES 


The largest record that DMP can process is 
limited by the amount of space available 
to the DMP task. DMP’s task image has 512 
(decimal) bytes allocated to it initially. 


The /RC switch and the /BL switch are 
mutually exclusive. 


/WD Specifies that the data be dumped in 
hexadecimal word format. 


6.4 DMP EXAMPLES 


Three examples of dump listings are included in this section to 
illustrate how the various DMP switches can be used. DMP edits 
blocks or records 16 (decimal) bytes at a time. The dump 
includes the indicated number of valid bytes in the block or 
record. The remaining number of bytes are listed as null bytes 
(305) se 


6.4.1 A Multiple Format Dump 


The following command line shown dumps virtual blocks 5 and 6 of 
DSC.MAC in hexadecimal, Radix-50, and decimal format. Each line 
of the output file will appear in three different formats. 


eo 


NAC DNMMP=]—[TIICPRETTPaAInGS MAC sBUY /RS5Y/TNe YT aug 
DMP>DOC .DMP= i USERFILES eere, a MAC /SHX/RO/DC/BL one sae @ 


The contents of DOC.DMP are: 


DUMP OF DW1:[USERFILES|]DSC.MAC;1 - FILE ID 17725,11,0 
VIRTUAL BLOCK 0,000005 - SIZE 512. BYTES 


4—E 41 4D 4D 4F 43 20 41 20 3B 00 1E 53 45 52 49 0000 raeP.6 
000000 MFY ML7 0 EFK EFQ LSK LN/ LT3 RS 
Oh PL0G5% 21317 « 00030.. 082als. UG25 he -2ZOZIts 19789. 20035.530C 
53 45 53 53 45 43 4F 52 50 20 44 4E 41 20 2C 44 0010 

000020 GCL JP2 J7F L22 L$SZ KCK MMK ML7 

LO% 113324 L661 25. 1486.. 20oiZ2s 20306, LI7 sl. 2roals 2isd ys 

53 52 49.46 20 3B 00 39 00. 3B 00 01. °2E 54 49 20 0020 


DMP EXAMPLES 


DUMP OF DW1:[USERFILES]DSC.MAC;1 - FILE ID 17725,11,0 


VIRTUAL BLOCK 0,000006 - SIZE 512. BYTES 


20: 44-4E° 46 55.4224 20 52 45 20.30 52: 20 46.-49 

000000 KI3 MEX EF M E E1H MYZ LT8 EFT 

0. 17993. 21024. 08240. 20805. 09248. 21826. 20038. 
44 4—F 45 09 00 09 50 4F 4F 4c 20 45 56 41 45 4c 

000020 KCT M2A EFU LST L39 I KA3 J7F 

16. 17740... 22081.. 08261. 20300; 20559... 00009. 17673. 


54 53 24 20 54 45 4c 09 00 2B 00 50 4F 4F 4C 20 


6.4.2 A Record Dump 


0000 


08260. 


0010 


17486. 


0020 


The following command line dumps all of the virtual records 


YACHT.SEQ in ASCII and decimal word format: 


DMP> REC .DMP=[ USERFILES ] YACHT.SEQ/RC/AS/DC 


The contents of REC.DMP are: 


DUMP OF DW1:[USERFILES]YACHT.SEQ;1 - FILE ID 15451,35,0 


RECORD NUMBER 01. - SIZE 41. BYTES 
000000 A Lb B E R G 3.067 M kK 
0% 195213. 27730. V6258., 08224. 08224. Alsi» 19744. 
000020 i: 2 K 2 2 © a a. 2 OD 20 
103. 18761... 08224. 17739. L236 US264. 14131. 12632. 
000040 O02 t 2 & 6 Oo 5 2 ere “eR “Oe ee 
32 12336. 12849. 13875. 13625. 00049. 00000, 00000. 
RECORD NUMBER 02. - SIZE 41. BYTES 
000000 A L B I N 7 9 
Oi. 19521. 18754. 08270. 08224. 08224. 14647. 08224. 


O=9 


of 


08267. 


12336: 


00000. 


08224. 


DMP EXAMPLES 


000020 EE -O OO. 2 2 6 0 4 2 
si oe OS224. 08224. 195392 20303. U8272. 13674. 12320. 12852. 
000040 0 0 1 QO 7 9 0 0°@ *@*@*@ *@ *e@ *@ 
ao 12330% 123375 147029. 12345... 00048.-00000.. 00000. 00000; 


6.4.3 A Header Dump 


The following command line dumps only the header of DSC.MAC. 


DMP>DHR.DMP=[USERFILES ]DSC.MAC/HD/BL:0 


The contents of DHR.DMP are: 


DUMP OF DW1:[USERFILES]DSC.MAC;1 - 


HEADER AREA 


H.IDOF 

H.MPOF 

H.FNUM, 

H.FSEQ 

H.FLEV 

H. FOWN 

H.FPRO 

H.UCHA 

H.SCHA 

H.UFAT 
F.RTYP 
F. RATT 
F.RSIZ 
F.HIBK 
F.EFBK 
F.FFBY 
(REST) 
000000 
000000 

IDENTIFICATION AREA 

I.FNAM, 

I.FTYP, 

I.FVER 

I. RVNO 

I.RVDT 

I.RVTI 

I.CRDT 

PeCRTI 

I. EXDT 


Plie- 2D LPI 255 bt 0 
FILE HEADER 


027 
056 


7S 4 
401 

[200,200] 

[| RWED, RWED, RWED, RWED |] 
000= 
000 


H 


002 
002 
116 
H:0 
H=0 
Dees 


R.VAR 
POOR 
TOs 
>000040 = 
:000040 = 
346. 


lI 


a2 
a2 


ee ae Se | 


000000 000000 000000 000000 000000 000000 000000 


DSC 

1 
13-OCT-80 
092 52246 
13-OCT-80 
09252245 


ie 2. 


DMP EXAMPLES 


MAP AREA 
M.ESON 000 
M.ERVN 000 
M.EFNU, 
M.EFSQ (0,0) 
M.CTSZ 004 
M.LBSZ 003 
M.USE 014 = 12. 
M.MAX 314 = 204, 
M.RTRV 
SIZE LBN 
1s H:000 L:036215 = 15501. 
3. H:000 L:036235 = 15517. 
i H:000 L:036250 = 15528. 
Ds H2000 L30362 72 =] 15546. 
Be H:000 L:036313 = 15563. 
ia H:000 L:036411 = 15625. 
CHECKSUM 
H.CKSM 122620 


6.5 DMP ERROR MESSAGES 
DMP -- BAD DEVICE NAME 


Explanations An incorrect device name was entered in a file 
Specriivcation. 


User Actions Reenter the command line specifying the 
correct device. 


DMP -- BLOCK SWITCH REQUIRED IN LOGICAL BLOCK MODE 
Explanation: /BL must be specified. 


User Actions Reenter the command line specifying the /BL 
Switch. 


DMP -- CANNOT FIND INPUT FILE 


Explanation: The requested file cannot be located in the 
specified directory. 


User Action: Reenter the command line specifying the 
correct file name and directory. 


DMP -- COMMAND SYNTAX ERROR 


Explanation: A command line was entered in a format that 
does not conform to syntax rules. 
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DMP 


DMP 


DMP 


DMP 


DMP 


DMP 


User Actions: 


DMP ERROR MESSAGES 


Reenter the command line specifying 


COrrece. Syntax. 


- FAILED TO ASSIGN LUN 


Explanation: 
Specification. 


User Actions: 


An illegal device was entered in a 


Reenter the command line specifying 


correct device. 


- FAILED TO READ ATTRIBUTES 


Explanation: 


A file was specified for which you _ did 


have read access privileges. 


User Action: 
protection of 


Rerun DMP after you have changed 
the file to READ access. 


- ILLEGAL SWITCH 


Explanation: 


Switch, or a legal switch was used in an invalid manner. 


User Actions: 


the 


file 


the 


not 


the 


A switch was specified that is not a valid DMP 


Reenter the command line specifying 


correct switch. 


- ILLEGAL USE 


Explanations: 


OF /RC SWITCH 


The /RC switch can be used only in file 


(see the beginning of this chapter). 


User Actions: 
name. 


Reenter the command line specifying a 


- ILLEGAL VALUE ON HD SWITCH 


Explanation: 


An option was entered other than F or U 


the /HD switch. 


User Actions: 


Reenter the command line specifying 


COrrect: ODtLON« 


- I/O ERROR ON INPUT FILE 


or 


- I/O ERROR ON OUTPUT FILE 


Explanations: 


One of the following conditions exists: 


the 


mode 


file 


For 


the 


@ 


@ 


DMP ERROR MESSAGES 


A problem exists on the physical device. 
The file is corrupted or the format is incorrect. 


The output volume is full. 


User Actions: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


DMP: ==" NO- INPUT PLibE: SPECIFIED 


Explanation: A command line was entered with no input’ file 
Specification. 


User Actions Reenter the command line specifying an input 
file. 


DMP -- NO LISTS OR WILD CARDS ALLOWED 


Explanations: Either a command line with more than one input 


or 


output file name was entered, or a wildcard was entered 


as a file specification. 


User Actions Reenter the command line, specifying only one 
input file specification and one output file specification. 
No wildcard specifications are allowed. 


DMP -- OPEN FAILURE ON INDIRECT FILE 


Explanation: The requested indirect command file does not 


exist as specified. One of the following conditions exists: 
cS) The file 1s protected against access. 

© A problem exists on the physical device. 

o The volume is not mounted. 

@ The specified file directory does not exist. 

) The named file does not exist in the specified 


directory. 


User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


DMP -- OPEN FAILURE ON INPUT FILE 
or 
DMP -- OPEN FAILURE ON OUTPUT FILE 
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DMP ERROR MESSAGES 


Explanations One of the following conditions exists: 


© 


@ 


S 


@ 


The file is protected against access. 
A problem exists on the physical device. 


The named file does not exist in the specified 
directory. 


The volume is not mounted. 


The specified file directory does not exist. 


User Actions Determine which condition caused the message 
and: COrrect (nat -Conadi1ticns, Reenter tne command ..tane. 


CHAPTER 7 
LIBRARIAN UTILITY PROGRAM (LBR) 


The Librarian Utility Program (LBR) allows you to create, update, 
modify, list, and maintain library files. A library file is a 
direct access file that contains a collection of related files. 
LBR organizes files, usually having the same file type, into 
library modules so that you have rapid and convenient access _ to 
your files. 


Library files contain two directory tables: the: Entry Pointe 
Table (EPT) and the Module Name Table (MNT). The EPT contains 
entry point names that consist of global symbols defined as entry 
points in MACRO source programs. The MNT contains names of the 
modules in the library. Both tables are alphabetically ordered. 


There are three kinds of library files: object, macro, and 
universal, described below. 


Object library Contain: ob 7ece files (.OBJ). The module 

files (.OLB) names are derived from .TITLE directives, while 
the entry point names are derived from global 
symbols defined in the module. LBR_ references 
the module code in the library by the module 
name. The source program references object 
library modules by the entry point name. Entry 
points apply only to object libraries. 


You use object module libraries as input to the 


Professional Application Builder (PAB). PAB 
searches for definitions of all global symbols 
referenced in a program in the following 
manner. First, PAB searches the other modules 
specified, then it searches the specified 
user-written object module LDA yy and 


finally, it searches the system library. 


Macro library contain source macro files (.MAC). The module 

files (.MLB) names are derived from .MACRO directives. From 
each macro definition, LBR extracts the name 
and creates an entry in the module name _ table. 
The entry in the module name table is the means 
by which the assembler finds the associated 
macro definition in the library. 


You use macro library modules as input to the 
Professional MACRO-11 Assembler. The assembler 
searches the specified library for macros 
listed in .MCALL statements and called in the 
source program before searching the system 
macro library. 


Universal contain modules inserted from any kind of file, 
library whether it be a program or text. The module 
Files (.ULB) names are either user-specified in the Insert 

(/IN) switch, or derived from the file name at 


the time of insertion. 


Primarily, you use universal libraries to 
package related files together. You. ‘can 
reference a universal library module in a 
program by using the Universal Library Access 
(SULA) system library routine. SULA, specified 
in the macro source program, establishes the 
necessary conditions for access (read-only) to 
a universal library module. 


Section 7.3 describes how you invoke LBR. 


7.1 FORMAT OF LIBRARY FILES 


A library file consists of a library header, an entry point 
table, a module name table, the library modules and their 
headers, and any available space. 


The entry point table has zero length for macro and universal 


libraries. Figure 7-1 illustrates object and macro library file 
format. Figure 7-2 illustrates universal library file format. 


7.1.1 Library Header 
The header section is a full block in which the first 24 


(decimal) words are used to describe the current status of the 
library. The header’s contents are updated as the library is 


nae 


FORMAT OF LIBRARY FILES 


modified. This allows LBR to access the necessary information to 
perform its functions (for example, Insert, Compress, and 
Delete). The twenty-fourth word in the library header is the 
default insert file type for universal libraries and is undefined 
for macro and object libraries. See Figure 7-3. 


7.1.2 Entry Point Table 


The entry point table consists of 4-word elements containing an 
entry point name (words 0-1) and a pointer to the module header 


of the module where the entry point is defined (words 2-3). See 
Figure 7-4. This table is searched when a library module is 
referenced by one of its entry points. The table is sequenced in 


order of ascending entry point names. The entry point table 
applies only to object library files. 


7.1.2.1 Module Name Table - The module name table is searched 
when the Jlibrary module is referenced by its module name rather 


than by one of its entry points. Tt is made up of 4-word 
elements: a module name (words 0-1) and a pointer to the module 
header (words 2-3). See Figure 7-5. The module name table is 


sequenced in order of ascending module names. 


7.1.2.2 Module Header - Each module starts with a header of 
eight words for object and macro modules and 32 (decimal) words 
for universal modules. The module header contains information 
about the module such as the type and status of the module, its 
length (number of words), and its attributes. See Figures 7-6 
and 7-7. 


In object and universal modules, the low-order bit of the 
attributes byte is set if the module has the selective search 
attribute. In universal modules, bit 1 of the attributes byte is 
set if the input file was contiguous. Also, in object modules, 
the two words of type-dependent information contain the module 
identification defined by the .IDENT directive at assembly time. 
In macro modules, these two words are undefined. 


For universal modules, type-dependent identification is derived 
from the file type and version number of the input file. 


Universal libraries allow you to change the module header, which 
contains optional descriptive information, by means of the Modify 
Header switch (/MH). 


FORMAT OF LIBRARY FILES 


FIXED- 
LENGTH 
RECORDS 


LIBRARY 
HEADER 


ENTRY POINT 
TABLE 
BLOCK 


BOUNDARIES 
MODULE NAME 


TABLE 


VARIABLE- MODULE 1 HEADER 
LENGTH 


RECORDS MODULE 1 


ZK-184-81 


Figure 7-1: General Format for Object and Macro Library Files 
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FIXED- 
LENGTH 
RECORDS 


LIBRARY 
HEADER 


ENTRY POINT 


TABLE 
BLOCK 


BOUNDARIES 


MODULE NAME 
TABLE 


VARIABLE- MODULE 1 HEADER 
LENGTH UNUSED SPACE 
RECORDS 


MODULE 1 


UNUSED SPACE 


MODULE 2 HEADER 
UNUSED SPACE 


MODULE 2 


UNUSED SPACE 


MODULE N HEADER 
UNUSED SPACE 


MODULE N 


AVAILABLE SPACE 


NOTE 


All universal module headers and the first record 
of each universal module will start ona block 
boundary. 


Figure 7-2: Universal Library File Format 
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OFFSET 


LIBRARY TYPE 


WORD 0 NON ZERO ID 

2 LBR (LIBRARIAN) VERSION 

4 (. IDENT FORMAT) 

6 YEAR 

10 DATE AND MONTH 

iz | TIME LAST DAY 

14 INSERT HOUR 
16 MINUTE 

20 SECOND 
2 
; 
: 
: 
: 
: 
: 
42 LOGICALLY DELETED 
44 AVAILABLE (BYTES) 
46 CONTIGUOUS SPACE 

50 AVAILABLE (BYTES) 

SZ NEXT INSERT RELATIVE BLOCK 

54 START BYTE WITHIN BLOCK 


56 UNIVERSAL DEFAULT INSERT TYPE+ 


LUNDEFINED FOR MACRO AND OBJECT LIBRARIES 
ZK-186-81 


Figure 7-3: Contents of Library Header 
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WORD 0 | GLOBAL SYMBOL | 


a NAME (RADS5O) 

Z ADDRESS OF RELATIVE BLK. 
MODULE oe eens 

3 HEADER BYTE IN BLOCK 


ZK-187-83 


Figure 7-4: Format of Entry Point Table Element 


WORD 0 MODULE NAME 
1 (RAD50) 
2 ADDRESS OF RELATIVE BLK. 
MODULE 
3 HEADER BYTE IN BLOCK 


ZK-188-81 


Figure 7-5: Format of Module Name Table Element 
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OFFSET FROM 
START OF 
MODULE HEADER 


OC, ATE RIBULES SLATUS O=NORMAL MODULE 
1=DELETED MODULE 


Z SLee OF 
4 MODULE (BYTES) | 
6 DATE 
MODULE 
10 INSERTED 


14 TYPE DEPENDENT 


16 INFORMATION 


ZK 189-81 


Figure 7-6: Module Header Format for Object and Macro Libraries 


OFFSET FROM 
START OF 


MODULE HEADER 


Figure 7-7: 


>» 


14 


16 


20 


PAP 


24 


26 


30 


Sz 


34 


76 
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ATTRIBUTES ee 


S26: OF 
MODULE XBYTES) 
DATE YEAR 


MODULE MONTH 


INSERTED DAY 


IDENT 


OPTIONAL 


INFO 1 


OPTIONAL 


INFO 2 


OPTIONAL 


INFO 3 


OPTIONAL 


USER 
FILE 
ATTRIBUTES 


ZK-190-81 


Module Header Format for Universal Libraries 
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Note to Figure 7-7 
Locations 40 (octal) through 76 (octal) contain user file 
attributes. User file attributes comprise the first of five 


sections in the FDB of the original file from which the module 
was created. The user file attributes are: 


@ Record type 

@e Record attribute 

@ Record size 

© Highest virtual block 

@ End of file block number 

® Optional information 
When you create a file and insert it into a universal Jlibrary, 
LBR copies the input file attributes to the module header. You 


can modify some of these attributes by using the modify header 
Switch (/MH). 


7.2 LBR RESTRICTIONS 

The following restrictions apply when using LBR: 
@ Limit of 65,536 (64K) words per module. 
© Limit of :.65,536. (64k) blocks per library. 


® Tables should be allocated their anticipated maximum size. 
Expanding table allocations requires using the Compress 
Switch (/CO) to copy the entire file. 


@® A fatal error results if an attempt is made to insert a 
module into a library that contains a module with a different 
name from, but with the same entry point as, the inserted 
module. For further information, refer to the discussion of 
the /IN switch in Section 7.5.8. 


@® The use of wildcards in file specifiers is not allowed (that 
is, forms such as *.OBJ, where the * indicates all modules 


with type .OBJ). 


LBR RESTRICTIONS 


The library’s tables must contain enough space for both the 
modules being replaced and their replacements, because the new 
modules are entered and the old modules are only logically (not 
physically) deleted. 


7.3. INVOKING LBR 

You can invoke LBR in two ways: 

1. Invoke one of the LIBRARY commands, which in turn invokes 
LBR. See Chapter 3 for a description of the LIBRARY 
commands. 

2. Invoke LBR directly from the DCL command level. 

To invoke LBR directly from the DCL command level, enter the 

following command: 

S RUN SLBR 


You receive a new prompt to indicate that you are in the LBR 
environment: 


LBR> 


Once you are in the LBR environment, LBR waits for your command. 
LBR accepts command lines in the following general format: 


Cutt i lel ,~Jastlule aint) yank te2j cn tien] 


LBR allows only one level of indirect command file nesting. 


7.4 DEFAULTS FOR LBR FILE SPECIFIERS 


Table 7-1 describes the defaults for LBR file specifiers. 


Table 7-1: 


Specifier 


dev: 


Paar} 


filename 


DEFAULTS FOR) DBR FELE. SPECIFIERS 


LBR File Specifiers Defaults 


Default 


Output File 
SLO: 


Listing File 
The device that was specified for the 
output file; otherwise, the default for 
the output file. 


Input File 
For the first input file specifier, SYQ:. 


For subsequent input file specifiers, the 
device specified in the previous input 
file specifier; otherwise, the default for 
the previous input file specifier. 


Output File 
The default directory under which LBR is 
currently running. 


Listing File 
The directory that was specified for the 
output file; otherwise, the default for 
the output file specifier. 


Input File 
For the £irst anput file -specitier, ‘the 
directory under which LBR 1s currently 
PUOnn In 


For subsequent input file specifiers, the 
directory specified in the previous input 
file specifier; otherwise, the default for 
the previous input file specifier. 


No default. Must be specified. 


DEFAULTS FOR LBR FILE SPECIFIERS 


Specifier Default 


. type Output File 


Depends on the default in effect 


(see 


Section 7.5.4), except when the Compress 
(7CO)-Or Create (/CR) Switch is specified 


(see Sections Pees t and 
respectively). 


Listing File 
Ba ps & 


Input File 
Refer to the descriptions of 


cies 


Compress 


(Sectton “7.0.1)% Ensert. (Sectron. 7.5.8). 
and Replace (Section 7.5.12) switches. 


sver Latest version of the file, or latest 


version 


plus 1 for the output file when the Compress 


(feO)>;. Create (/CR), Or. -ExXtract (/EX) 
are specified. 


/switch Output File 
/IN (Insert) 


List File 
/LI (List module names) 


Input File 
None 


7.5 LBR SWITCHES 


LBR uses switches appended to file specifications to 
functions. These switches are summarized in Table 7-2. 


Switches 


invoke 


LBR SWITCHES 


Table 7-2: LBR Switches 


Option Switch Function 

Compress 7 CO Compress a library file. 

Create FoR Create a library file. 

Delete /DE Delete a library module and all its 


entry points. 


Default /DE Specify default library file type. 
Delete Global /DG Delete a library module entry point. 
BNtCrY .POLne /EP Include entry point elements in the 


library entry point table. 


/-~EP Exclude entry point elements in the 
library entry point table. 


Extract / EX Extract (read) one or more modules 
from a library file and write them 
into a specified output file. 


Insert ZINN Insert a module. 
List aret List module names. 
/LE List module names and entry points. 
JEU List module names and full module 
description. | 
Modify Header /MH Modify a universal module header. 
Replace /RP Replace a module. 
/~RP Do not replace a module. 
Selective Search ZOS Set the selective search attribute 


in the module header. 
Squeeze Zoe Reduce the size of the macro source. 


{/-S8Z Do not reduce the size of a specific 
macro source. 


LBR SWITCHES 


7.5.1 Compress Switch (/CO) 


Use the Compress switch (/CO) to physically delete all logically 
deleted records, to put all free space at the end of the file, 
and to make the free space available for new library module 
inserts. Additionally, the library table specification may be 
altered for the resulting library. LBR accomplishes this by 
creating a new file that 1S a compressed copy of the old library 
file. The old library file is not deleted after the new file is 
created. 


The /CO switch can be appended only to the output file 
Specification. The format for specifying the /CO switch 1s: 


outfile/CO:size:ept:mnt=infile 


outfile: 


Specifies the file that is to become the compressed version 


of the input file. The default file type is .OLB if the 
Input file-1s:an obj ect. library; «MER 1f the: input 116 1s a 
macro library, or .ULB if the input file is a universal 
library. 

/CO 
Specifies the Compress switch. 

:size 
Specifies the size of the new library file i 256 
(decimal)-word blocks. The size of the old library file is 
the default size. 

sept 


Specifies the number of Entry Point Table (EPT) entries to 
allocate. If the value specified is not a multiple of 64 
(decimal), the next highest multiple of 64 (decimal) is 
used. The number of EPTs in the old library file is the 
default value. This parameter is always forced to zero. for 
macro libraries and universal libraries. The maximum number 
of entries is 4096 (decimal). 


LBR SWITCHES 


smnt 
Specifies the number of Module Name Table (MNT) entries to 
allocate. If the value specified is not a multiple of 64 
(decimal), the next highest multiple of 64 (decimal) is 
used. The number of MNTs in the old library file is the 
default value. The maximum number of entries is 4096 
(decimal). 

infile 
Specifies the library file to be compressed. The default 
rile: type 2S «OLB for Ob}ect 2bbraries; .MLe tor macro 
libraries, and .ULB for universal libraries. The actual 
default file type is determined by the current default 
library file type (see Section 7.5.4). 

Example 


LBR>RICKLIB/CO:100.:128.:64.=SHEILA.OLB 


In this example, file SHEILA.OLB is compressed, and a new 
file, RICKLIB.OLB, is created with the following attributes: 


size = 100 (decimal) blocks 
EPT = 128 (decimal) entry points 
MNT = 64 (decimal) module names 


The new file, RICKLIB.OLB, receives a version number that 1s 
one version greater than the latest version for the file. 


Both files, RICKLIB.OLB and SHEILA.OLB, reside in the 
default directory file on SyY0:. 


7.5.2 Create Switch (/CR) 

Use the Create switch (/CR) to allocate a contiguous library 
File. The switch initializes the library file header, the entry 
point table, and the module name table. 


The /CR switch can be appended only to the output file 
specification. The format for specifying the /CR switch is: 


outfile/CR:size:ept:mnt:libtype:infiletype 


LBR--SWLTCHES 


outfile 


Specifies the library file being created. The default file 
type is .OLB if an object library is being created, .MLB if 
a macro library is being created, or .ULB if a universal 
library is being created. 


/CR 
Specifies the Create switch. 

:size 
Specifies the new library file size in disk (256 decimal 
word) blocks. The default size is 100 (decimal) blocks. 

sept 
Specifies the number of Entry Point Table (EPT) entries to 
allocate. The default value is 512 (decimal) for object 
libraries. This parameter is always forced to zero for 
macro libraries and universal libraries. The maximum number 
of entries is 4096 (decimal). 

smnt 
Specifies the number of Module Name Table (MNT) entries’ to 
allocate. The default.vailue is 2560 (decimal). ‘The maximum 
number of entries is 4096 (decimal). 

:libtype 
Specifies the type of library to be created. Acceptable 
values are OBJ for object libraries, MAC for macro 
libraries, and UNI for universal libraries. The default is 
the last value specified or implied with the /DF switch (see 
Section 7.5.4), or OBJ if /DF has not been specified. 

sinfiletype 


Specifies the default input file type for the created 
universal library. If this value is not specified, the 
default input file type for universal libraries i1s_ .UNI. 
This value is not defined for object or macro libraries. 
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If the values specified for EPT and MNT are not multiples of 64 
(decimal), EPT and MNT are automatically filled out to the next 
disk block boundary. 

Example 


LBR>ORICKLIB/CR: :128.:64.:O0BJ=SHEILA, LAURA, JENNY 


In this example, a combination of functions is performed. 
First, the library file RICKLIB.OLB is created in the 


Getauit- directory ‘on isy0e. RICKLIB has the following 
attributes: 

size = 100 (decimal) blocks (default size) 

EPT = 128 (decimal) entry points 

MNT = 64 (decimal) module names 

type = .OBJ 


Secondly, object modules from the input files SHEILA.OBJ, 
LAURA.OBJ, and JENNY.OBJ, which reside in the default 
directory on SY0:, are inserted into the newly created 
library file. Insert (/IN) is the default switch for input 
Files (see Section 7.5.8). 


7.5.3 Delete Switch (/DE) 


Use the Delete switch (/DE) to logically delete library modules 
and their associated entry points (global symbols) froma library 
file. Up to 15 (decimal) library modules and their associated 
entry points can be deleted with one delete command. 


When LBR begins processing the /DE switch, it prints’ the 
following message on the terminal screen: 


MODULES DELETED: 


As modules are logically deleted from the library file, the 
module name iS printed on the terminal screen. (See the example 
at the end of this section.) 


If a specified library module is not contained in the Ilibrary 
file, a message iS printed on the terminal screen and the 
processing of the current command is terminated. This message is 
as follows: 


LBR -- *FATAL*-NO MODULE NAMED "name" 


The /DE switch can be appended only to the library file 
specification. 


LBR SWITCHES 


When LBR deletes a module from a library file, the module is not 
physically removed from the file, but is marked for deletion. 
This means that, although the module is no longer accessible, the 
file space it once occupied is not available (unless the deleted 
module was the last one inserted). To physically remove the 
module from the file and make the freed space available, you must 
compress the library (see Section 7.5.1). 


The format for specifying the /DE switch is: 
outfile/DE:modulel[:module2...:modulen|] 


outfile 


Specifies the library file. 


/DE 

Specifies the Delete switch. 
smodule 

Specifies the name of the module to be deleted. 
Example 


LBR>RICKLIB/DE: SHEILA: LAURA: JENNY 

MODULES DELETED: 

SHEILA 

LAURA 

JENNY 

In this example, the modules SHEILA, LAURA, and JENNY and 


their associated entry points are deleted from the latest 
version of library file SYU:RLCKLIB:OLB. 


7.5.4 Default Switch (/DF) 


Use the Default switch (/DF) to specify the default library 
file type. Acceptable default values are OBJ for object 
libraries, MAC for macro libraries, and UNI for universal 
libraries. 
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When a default library file type is not specified by the /DF 
Switch, OBJ is the default library file type. 


Specifying a default value: 


1. Sets the default file type for the Create switch (/CR). 


2. Provides a file type default value of .MLB for macro 
libraries, -.ULB for universal libraries, and .OLB for 
object libraries when opening an output (library) file. 


Exceptions to this occur when you use /CO or /CR. When 
you specify /CO, the default applies to the library 
input file. When you specify /CR, the default file type 
is .OLB if an object library is being created, .ULB if a 
universal library is being created, or .MLB if a macro 
library is being created. 


The /DF switch only affects the file type of the file to 
be opened. After that, the library header’ record 
information is used to determine the type of library 
file being processed. 


The /DF switch can be issued alone or appended to a library file 
specification. The format for specifying the /DF switch is: 


outfile/DF:filetype... 


or 


/DF: filetype 


outfile 


/DFE 


Specifies the library file. 


Specifies the Default switch. 


filetype 


Specifies the default library file type: OBJ for object 
library files, MAC for macro library files, and UNI for 
universal library files. 


Tf a value other than OBJ, ULB, or MAC is specified, the 


current default library type will be set to object libraries 
and the following message will be displayed: 
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LBR -- *FATAL*-INVALID LIBRARY TYPE SPECIFIED 


Examples 


LBR>/DF:MAC 
LBR>RICKLIB=infile 


The file RICKLIB.MLB is opened for insertion. 


LBR>/DF:MAC 
LBR>RICKLIB/DF:OBJ=infile 


OBJ replaces MAC as the default filetype. The file 
RICKLIB.OLB is opened for insertion. 


LBR>/DF:MAC 
LBR>RICKLIB/CR 


The macro library RICKLIB.MLB is created. 


LBR>/DF:MAC 
LBR>RICKLIB/CR::::OBJ 


Because OBJ is specified, it overrides the default (MAC). 
The object library RICKLIB.OLB is created. 


LBR>/DF: OBJ 
LBR>TEMP/CO=RICKLIB.MLB 


Because RICKLIB.MLB is a macro library, MAC overrides’ the 
default (OBJ). The macro library file TEMP.MLB is created 


to receive the compressed output. 


LBR>/DF:UNI 
LBR>RICHLIB=TEST 


The file RICHLIB.ULB is opened for insertion. 


7.5.5 Delete Global Switch (/DG) 


Use the Delete Global switch (/DG) to delete a specified entry 
point (global symbol) from the EPT. Up to 15 (decimal) entry 


points may be deleted with one command. This command does not 
affect the object module that contains the actual symbol 
definition. You may wish to delete an entry point if a module to 


be inserted has the same entry point. 


When LBR begins processing the /DG switch, it prints’ the 
following message on the terminal screen: 
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ENTRY POINTS: DELETED: 
As entry points are deleted from the library file, the entry 
point is printed on the terminal screen. (See the example at the 
erd Of this section.) 
If a specified entry point is not contained in the EPT, a message 
is printed on the terminal screen and the processing of the 
current command is terminated. This message is as follows: 


LBR -- *FATAL* - NO ENTRY POINT NAMED "name" 


The /DG switch can only be appended to the library file 
specification. 


The format for specifying the /DG switch is: 
outfile/DG:globali[:global2...:globaln] 


outfile 


Specifies the library file. 


/DG 

Specifies the Delete Global switch. 
global 

Specifies the name of the entry point to be deleted. 
Example 


LBR>RICKLIB/DG: SHETLA: LAURA: JENNY 

ENTRY =POTLNTS: DELETED: 

SHETLA 

LAURA 

JENNY 

In this example, the entry points SHEILA, LAURA, and JENNY 


are deleted from the latest version of the library file 
named SY0:RICKLIB.OLB. 
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7.5.6 Entry Point Switch (/EP) 


Use the Entry Point switch (/EP) to control (include or exclude) 
the placement of global symbols ina library entry point table. 
The switch can be specified in either a positive or negative 
format: 


/EP Include entry points in the entry point table. 

/-EP Do not include entry points in the entry point 
table. 

/NOEP Do not include entry points in the entry point 
table. 


The positive format (/EP) causes all entry points ina module or 
modules to be entered in the library entry point table. 


Either negative format (/-EP or /NOEP) provides for a module to 
be included ina library, but excludes the entry points in that 
module from being entered in the library entry point table. 


/EP is the LBR default. If the switch is not specified, all 
entry points are entered into the library entry point table. 


The /EP switch has no effect on macro or universal libraries. 


The format for specifying the /EP switch is: 


outfile[ /EP ]J=infile,...infilen 
freer 4 
[ /NOEP ] 
or 


Outtile=iniile] 7Ee lipsssiIntiten| yer | 
L=VEE: | L=7RE} 
[/NOEP | [ /NOEP ] 


outfile 


Specifies the output file. When the entry point switch is 
applied to this file specification, LBR assumes each of the 
input files contains modules for which entry points are _ to 
be either included or excluded. 
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infile 


Specifies an input file. When the /EP switch is applied to 
an input file specification, LBR assumes only the input 
files to which the switch is applied contain modules’ for 
which entry points are to be either included or excluded. 


NOTE 


Although not reflected in the command formats, 
the positive and negative forms of the switch may 
be applied to both the output and input file 
specifications. For example, the effect of /EP 
applied to the output file can be overridden by 
applying /-EP to a specific input. file. 


The /-EP switch is useful for including modules that contain 
duplicate entry point names in the same library. The /-EP switch 
provides the means for entering a module in the library without 
having its entry points included in the library entry point 
table. 


The /-EP switch is also useful in the case where the Task Builder 
uses only module names to search for modules in an object module 
library. In this case, entries in the library entry point table 
are not required. The /-EP switch can be used to exclude entry 
points from being entered in the library entry point table. 


Depending on whether the /EP switch is applied to the output 
Specification. <r “CO. «am IApUuc -SpecrTication;, Lt. has.e1ther a 
Global or Local er iect.. 


When applied to the output file specification, the /EP switch has 
a global effect. That is, LBR either includes all entry points 
im the entry point: table or excludes all entry points. from...being 
entered in the entry point table. 


When applied to an input file specification, the Entry Point 
switch has a local effect. That is, LBR either includes entry 
points in the entry point table, or excludes entries from being 
entered in the entry point table for only those modules to which 
the switch is applied. 


Entry points in an object module are not affected by the /EP 
Switch. The switch only affects entries in the library entry 
point table. 
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7.5.7 Extract Switch (/EX) 


Use the Extract switch (/EX) to extract (read) one or more 
modules from an object or macro library file and write them into 
a specified output file. If more than one module is extracted, 
the modules are concatenated in the output file. The extract 
operation has no effect on the library file from which the 
modules are extracted; that file remains intact. Up to eight 
modules may be specified in one extract operation for object and 
macro libraries. However, only one module may be specified in 
one extract operation for a universal library. 


For object and macro libraries, if no modules are specified in 
the command line, all modules in the library are extracted and 
concatenated in the output file in alphabetical order. 


For universal libraries, RMS fields cannot be extracted to a 
record-oriented device, such as a terminal. 


The /EX switch may be applied only to input file specifications. 
The format for specifying the /EX switch is: 


outfile=infile/EX[:modulenamel...:modulenamen|] 


outfile 


Specifies the file into which extracted modules are to _ be 
stored. The default file type for this file is .OBJ if the 
input modules are object modules. The default file type is 
.MAC if the input modules are macro modules. If the library 
is a universal library, the outfile retains the infile type 
of the module extracted. (However, you are allowed to 
extract only one universal library module at a time.) 


infile 
Specifies the library file from which the modules are to be 
extracted. The default file type is .ULB, .OLB, or .MLB, 


depending on the current default library type. 


/EX 


Specifies the Extract switch. 
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modulename 


Specifies the name of the module to be extracted from the 
11 brary. 

Examples 
LBR>DRIVERS=RSX11M/EX: DXDRV: DKDRV: TTDRV 


The object modules DXDRV, DKDRV, and TTDRV are concatenated 
in alphabetical order and written into the file DRIVERS.OBJ. 


LBR>TI:=[{1,5]RSXMAC.SML/EX:QIOSS 
The macro QIOSS is written to the terminal screen. 
LBR>TEST .OBS=TEST/EX 


All of the modules in the library TEST.OLB are written into 
the file TEST.OBS in alphabetical order. 


7.5.8 Insert Switch (/IN) for Object and Macro Libraries 


Use the Insert switch (/IN) to insert modules into a library 


file. Any number of input files can be specified. For object 
and macro libraries, each input file can contain any number of 
concatenated input modules. For macro Libraries, ‘only 


first-level macro definitions are extracted from the input files. 
All text outside of the first-level macro definitions is ignored. 
(The Insert switch for Universal Libraries, 1s explained in 
Section 7.5.9.) The /IN switch is the default library file option 
and can be appended only to the library file specification. 


If you attempt to insert an input module that already exists in 
the library file, the following message is printed on the 
terminal screen: 


LBR -- *FATAL* DUPLICATE MODULE NAME "name" IN filename 
Likewise, if you attempt to insert a module and a module contains 
an entry point that duplicates one that is already in the EPT, 


the following message is printed on the terminal screen: 


LBR -- *FATAL* DUPLICATE ENTRY POINT "name" IN filename 
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The format for specifying the /IN switch is: 


euciile[7IN|=intilel| , inti le? ,...<intilen) 


outfile 


Specifies the library file into which the input modules are 
to be inserted. The default file type depends on the 
current default (see Section 7.5.4). It is .0OLB if the 
current default is object libraries, .MLB if the current 
default is macro libraries. 


/IN 
Specifies the Insert switch. 

infile 
Specifies the input file containing the modules to _ be 
inserted into the library file. The default file type is 
.OBJ 1£ the outfile 1s an object library and .MAC if the 
outfile is a macro library. 

Example 


RICKLIB/IN=SHEILA, LAURA, JENNY 


In this example, the modules contained in the latest 
versions SHEILA, LAURA, and JENNY, which reside in the 
default directory on SY0Q:, are inserted into the latest 
version of the library file RICKLIB, which also resides in 
the default directory on SY0:. The default file type _ for 
SHEILA, LAURA, and JENNY is .OBJ if RICKLIB is an object 
module library, or .MAC if RICKLIB is a macro library. 


7.5.9 Insert Switch (/IN) for Universal Libraries 


The Insert switch (/IN) works basically the same for universal 
libraries as it does for object and macro libraries. However, 
when inserting a file into a universal library, the /IN switch is 
applied to the input file rather than the output file. You can 
also specify module name and descriptive information as switch 
values in the command line. In addition, LBR copies input file 
attributes to the module header. 
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The high block indicator (F.HIBRK of the file’s descriptor block) 
and the end of file indicator (F.EFBK of the file’s FDB) are 
included in the input file’s user file attributes. LBR makes the 
high block indicator equal to the end of file indicator in the 
module header. This means that when a module is extracted to a 
file, that file will have as many blocks allocated to it as are 
used. 


The format for specifying the /IN switch for universal libraries 
iS% 


outfile=infile/IN:name:op:op:op:op 

outfile 
Specifies the universal library into which the infile is to 
be inserted. 

infile 


Specifies ‘the input file to. be inserted into ehe “ourtile. 
The default for the file type is the value indicated at the 


universal library’s creation time. See Section 7.5.2. 

/IN 
Specifies the Insert switch. 

sname 
Optionally specifies the module name (up to six Radix-50 
characters). The default is the first six characters of the 
input file name. 

:Op 
Specifies optional descriptive information (up to S1X 
Radix-50 characters) to be stored in the module header. The 
default 16 null. Tf “only part of “the Intormation. set. 1s 
specified, all preceding colons must be supplied. 

Example 


LBRORICKIIB. ULB=J0OE.TAT/ZINeMODIATHIS : 1S20AN2Z STEXT 
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In this example, LBR inserts JOE.TXT into the universal 
library RICKLIB.ULB as MOD1. ETH LS" 3 "ES: “JANZ" » and 
"TEXT" are stored in the module header. 


You can insert JOE.TXT without the /IN switch and its 
values. As a result, all the information normally specified 
by the switch values defaults as described in this example. 


7.5.10 List Switches (/LI, /LE, /FU) 


Use the list switches to produce a printed listing of the 
contents of a library file. Three switches allow you to select 
the type of listing desired. These switches are as follows: 


/LI Produces a listing of the names of all modules in 
the library file. 


/LE Produces a listing of the names of all modules in 
the library file and their-.corresponding entry 
points. 

/FU Produces a listing of the names of all modules in 
the library file and gives a full module 
description for each: that is, size, date of 


insertion, and module-dependent information. 


These switches can be appended only to the output file 
specification or the list file specification. 


The /LI switch is the default value. It need not be specified 
when a listing file has been specified or when any other list 
Switch is included in the command line. 

The format for specifying list switches 1s: 


outfile[,listfile]/switcn(es) 


outfile 


Specifies the library file whose contents are to be listed. 


listfile 


Optionally specifies the listing file. If not specified, 
the listing 1s: directed ‘to ‘the termindl, screen. 
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/switch(es) 


Specifies the list option(s) selected. 
Examples 
LBRORULCKLIB LI 


In this example, a listing of the names of all the modules 
contained in file SY0:RICKLIB.OLB is printed on the terminal 
screen. 


LBR>RICKLIB/LE 


In this example, a listing of the names of all the modules 
and their entry points (contained in file SY0:RICKLIB.OLB) 
is printed on the terminal screen. 


LBR>RICKLIB/FU 


In this example, a listing of the names of all the modules 
in file SY0:RICKLIB.OLB, and a full description of each one 
contained is printed on the terminal screen. 


In this example, LBR creates file LP.LST in directory 
[FOOBAR] on DW1, which lists the module names, their entry 
polnts, and. ia full. description. of <eacn. module for fie 
RICKLIB. 


7.5.11 Modify Header Switch (/MH) 

The Modify Header switch (/MH) pertains only to universal 

libraries and allows you to modify the optional user-specified 

information in the module header. 

The format for specifying the /MH switch is: 
outfile/MH:module:op:op:op:op 


outfile 


Specifies an output file for the universal library. The 
File type defaults to .ULB. 
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/MH 
Specifies the Modify Header switch. 

smodule 
Specifies the name of the module whose descriptive 
information is to be modified. 

sop 


Specifies the optional user information (up to six Radix-50 
characters) to be stored in the module header. The default 
1s null and indicates that the corresponding information 
field is not to be changed. Also, entering a pound sign (#) 
clears the corresponding information field. 


Example 


The optional descriptive information for module A of 
RICKLIB.ULB is: 


"MODA" "FCHCD" Op "eCH" 
The LBR command is: 
LBR>RICKLIB/MH:A:FCHTS:#:: 


The optional descriptive information for module A in file 
RICKLIB is changed to: 


w FCHTS" f " "Or "RCH" 


7.5.12 Replace Switch (/RP) For Macro and Object Libraries 


Use the Replace switch (/RP) to replace modules ina library file 
with input modules of the same name. Any number of input files 
are allowed and each file can contain any number of concatenated 
input modules. 


For macro libraries, only first-level macro definitions are 
extracted from the replacement files. : 


When a match occurs on a module name, the existing module is 
logically deleted and its entries are removed from the EPT. 
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As each module in the library file is replaced, a message is 
printed on the terminal screen. This message, which contains the 
name of the module being replaced, is as follows: 


MODULE "name" REPLACED 


If the module to be replaced does not exist in the library file, 
LBR assumes that the input module is to be inserted and 
automatically inserts it without printing a message. 


The /RP switch can be specified in either of the following 
formats: 


@ Global format - The /RP switch is appended to the library 
file specification and all of the input files are assumed 
to contain replacement modules. 


@e Local format - The /RP switch is appended to an input 
file “<spécification. and. only ‘the file -to. which. the /RP 
Switch is appended is considered to contain replacement 
modules. 
Global Format 
outfile/RP=infilei[,infile2,...infilen] 
outfile 
Specifies the library file. The default file type depends 
on the current default (see Section 7.5.4). It is .OLB if 


the current default is object libraries or .MLB if the 
current default is macro libraries. 


Specifies the Replace switch. 

infile 
Specifies the input file that contains replacement modules 
for the library file. The default type is .OBJ if outfile 


is an object library or .MAC if it is a macro library. 


The Global format allows you to specify a list of input files 
without having to append the /RP switch to each of them. 
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To override the global function for a particular input file (that 
is, to instruct LBR to process a particular file in a list as a 
file containing modules to be inserted but not replaced), append 
/-RP or /NORP to the desired input file specification. 

Local Format 


outfile=infilel[{/RP][,infile2[/RP],...infilen[/RP] ] 


outfile 


Specifies the library file. The local format default is the 
same as the global format default. 


infile 
Specifies the input file that contains replacement modules 


for the output library file. The local format default is 
the same as the global format default. 


/RP 
Specifies the Replace switch. Appending the /RP switch to 
an input file specifier constitutes the local format of the 
Switch. This overrides the LBR default (/IN) and instructs 
LBR to treat the module(s) contained in the specified file 
as replacement modules. 

Examples 


The files used in the following four examples, and_ the 
modules contained within each file, are depicted in Figure 
7-8. These files are assumed to reside in the default 
directory on the default device and the initial state of the 
library file is assumed to be as shown in Figure 7-8. 


‘a LBR>RICKLIB/RP=SHETLA, LAURA, JENNY 
MODULE "SHEILA" REPLACED 
MODULE "LAURA1" REPLACED 
MODULE "LAURA2" REPLACED 
MODULE "JENNY1" REPLACED 
MODULE "JENNY2" REPLACED 
This example uses the global format for the /RP switch. 


Object modules from the input files SHEILA, LAURA, and 
JENNY replace modules by the same names in the library 
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file RICKLIB, and modules JENNY3 and LAURA3 are 
inserted. Figure ./-9 shows the resulting library file. 
LBR>RICKLIB=CHRIS, SHEILA/RP 
MODULE "SHEILA" REPLACED 


In this example, the local format of the /RP switch is 


used. The object module SHEILA from file SHEILA is 
replaced in the library file RICKLIB. The object 
modules in the file CHRIS are inserted in the library 
file. (See the description of the /IN switch in Section 
7.5.8.) The resulting library file is shown in Figure 
7-10. 


LBR>RICKLIB/RP=SHEILA, LAURA, JENNY, CHRIS/-RP 


MODULE "SHEILA" REPLACED 
MODULE "LAURA1" REPLACED 
MODULE "“LAURA2" REPLACED 
MODULE "JENNY1" REPLACED 
MODULE "JENNY2" REPLACED 


In this example, the /-RP switch is used to override the 
global format of the command. Object modules in files 
SHEILA, LAURA, and JENNY are processed as modules to be 
replaced, and file CHRIS is processed as a file that 
contains modules to be inserted. The resulting library 
file 1s shown in Figure 7-11. 


LBR>RICKLIB/RP=SHEILA, LAURA/-RP, JENNY 


MODULE "SHEILA" REPLACED 
LBR -- *FATAL* -- DUPLICATE MODULE "“LAURAI" IN 
LAURA.OBJ;1 


In this example, only module SHEILA from file SHEILA was 
replaced. The user specified that the modules in file 
LAURA not be replaced (/-RP), but inserted. One of the 
modules contained in file LAURA duplicated an already 
existing module in file RICKLIB. Therefore, LBR issued 
the fatal error message and terminated the processing of 
the current command line. 
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INPUT FILES 


RICKLIB.OLB;1|/SHEILA.OBJ; 1/LAURA.OBJ;1)JENNY.OBJ;1] CHRIS.OBJ;1 


LAURAIL JENNY1 CHRIS1 
LAURA2 | JENNY2 CHRIS2 | 
LAU RA3 JENNY 3 


ZK-191-81 


OUTPUT 
LIBRARY FILES 


FILE NAME 


OBJECT 


JENNY] SHEILA 


JENNY2 


MODULES 


LAURAIL 
LAURA2 
SHEILA 


Figure 7-8: Sample Files Used in LBR Examples 1-4 


RICKLIBi.OLBs 1 


JENNY1L 


JENNY 2 


LAURAL 


oe 
ao 
CG 
5 
No 


| 
| 
| 
JENNY31 
| 
| 


SHEILA 


1. These modules did not exist in the 
library file prior to the exegution of 
this example, but they did exist in the 
input files. LBR, therefore, assumed 
that they were to be inserted. Since 
LBR handled these modules as a normal 
insert, no message was printed on the 


input terminal. 
ZK-192-81 


Figure 7-9: Output Library File After Execution of Example 1 
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RICKLIB.OLB;1 


CHRIS1 


CHRIS2 


JENNY1 


JENNY 2 


LAURAL 


LAURA2 


SHEILA“ 


1. These modules are inserted. 


2. This module is replaced. 
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Figure 7-10: Output Library File After Execution of Example 2 


RICKLIB.OLB; 1 


curisit 


CHRIS2? 


JENNY 1 


JENNY 2 


JENNY 3° 


LAURA1L 


LAURA2 


LAURA3* 


| 
SHEILA | 


1. These modules were specified to be 
inserted. Had a module of the same name 
peen present, a fatal error message 
would have been issued. See Example 4. 


2. These modules were inserted bydefault. 
ZK-194-81 


Figure 7-11: Output Library File After Execution of Example 3 
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7.5.13 Replace Switch (/RP) for Universal Libraries 


Use the /RP switch for universal libraries in the same way as for 


macro and object libraries. However, you can also specify the 
same values for the /RP switch as for the /IN switch for 
universal libraries. See Section 7.5.9. 


As with macro and object libraries, you can specify the /RP 
switch with either the output file specification or with the 
input file specifications. 
The global format of the /RP switch for universal libraries is: 
outftile/RPsname:op:optop:Op=intile[,,infile2,..1+.intilen] 
The local format of the /RP switch for universal libraries is: 
outfile=infile/RP:name:op:op:op:op[,infile2....infilen] 
outfile 
Specifies the universal library file. 
infile 
Specifies the input file that contains replacement modules 
for the library file. The default for the file type is the 


value indicated at the universal Jlibrary’s creation time. 
See Section 7.5.2. 


/RP 
Specifies the Replace switch. 

sname 
Optionally specifies the module name to be replaced (up _ to 
Six Radix-50 characters). The default is the first six 
characters of the infile name. 

:Op 
Specifies optional descriptive information (up to six 
Radix-50 characters) to be stored in the module header. The 
default is null. If only part of the information set 1s 
specified, all preceding colons must be supplied. 

Example 


LBROTEXT <ULB=DEBBIEsTXT7ZRP? + THIS: IStgANS UPDATE 


MODULE "DEBBIE" REPLACED 
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In this example, LBR replaces the module DEBBIE in the 
universal library TEXT.ULB with an updated module from file 
DEBBIE.TXT. The date of replacement is specified by the 
optional user information and inserted in the module header. 
Note that the optional name is omitted. 


The initial state of the library file is shown in Figure 
7-12. The resulting library file is shown in Figure 7-13. 


OUTPUT 
LIBRARY FILE INPUT FILES 


FILE NAME FEXTCULB DEBBIE.TXT 


nl ae 


ZK-195-81 


Figure 7-12: Sample Files for Universal Library Replace Example 


TEx. UBS 


DEBBIE 
BERNIE 


1.The module DEBBIE was replaced. dee * sa 
different infile were specified, that 


would become module DEBBIE and 


occupy the same location in TEXT.ULB. 


ZK-196-31 


Figure 7-13: Output Library File After Library Replace 
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7.5.14 Selective Search Switch (/SS) 


Use the Selective Search switch (/SS) to set the selective search 
attribute bit in the module header of object modules as they are 
inserted into an object library. The switch has no effect when 
applied to modules being inserted into a macro library. The 
Switch may be specified with input files for insertion or 
replacement operations only, and it affects all modules in the 
input file to which it is applied. 


Object modules with the selective search attribute are given 
Special treatment by the Task Builder. Global symbols, defined 
in modules with the selective search attribute, are only included 
in the Task Builder’s symbol table if they are previously 
referenced by other modules. Thus, only referenced symbols will 
be listed with the module in the Task Builder memory allocation 
file, thereby reducing task build time. The /SS switch should 
only be applied to object files whose modules contain only 
absolute (not relocatable) symbol definitions. 


The format for specifying the /SS switch is: 
outfile=infilel/SS[,infile2[/SS],...infilen[/SS] ] 


outfile 


specifies ‘the Library file. 

infile 
Specifies the input file that contains modules to _ be 
selectively searched. 
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Specifies the Selective Search switch. 
Example 


LBR>ANGEL=JOHN, JILL/SS,MARK/SS ,MARY 


The object files JOHN.OBJ, JILL.OBJ, MARK.OBJ, and MARY.OBJ 
are inserted into object library ANGEL.OLB. The selective 
search attribute bit is set-in both the JILL and MARK object 
module header. 


LBR SWITCHES 


7.5.15 Squeeze Switch (/SZ) 


Use the Squeeze switch (/SZ) to reduce the size of macro 
definitions by eliminating all trailing blanks and tabs, blank 
lines, and comments from macro text. The /SZ switch is used to 
conserve memory in the MACRO-11 Assembler and to reduce the size 
of macro library files. The /SZ switch has no effect on object 
libraries or universal libraries. 


The /SZ switch can be specified in either of two formats: 
@ Global format - The /SZ switch is appended to the library 
File specification. All of the input files are assumed 
to contain modules to be squeezed. 
@ Local format - The /SZ switch is appended to an input 


file specification. The /SZ switch works only on the 
file to which you append it. 


Global Format 
outftile/SZ=inftilel[,intile2,;...inftilen|] 


outfile 


Specifies the library file. 


{SZ 


Specifies the Squeeze switch. 


infile 


Specifies the input file that contains modules to _ be 
squeezed during insertion into the library file. 


Use the global format of the /SZ switch to specify a list of 
input files without having to append the /SZ switch to each of 
them. To override the global function for a particular input 
tile: (that is; to instruct. DER. fo process a particular tite ana 
list as a file containing modules to be inserted but not 
Squeezed), append /-SZ or /NOSZ to the desired input file 
Specification. 


Local Format 


outfile=infile1/SZ[,infile2[/SZ]...,infilen[/82]] 
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outfile 


Specifies the library file. 

infile 
Specifies the file that contains modules to be squeezed 
during insertion into the library file. 
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Specifies the Squeeze switch. 


LBR uses the following algorithm on each line to be squeezed and 
then inserts the resulting line into the library file: 


1. The line is examined for the rightmost semicolon (;). 


2. If a semicolon is located, it is deleted, along with all 
trailing characters in the line. 


3. All trailing blanks and tabs in the line are deleted. 


4. If the resulting line is null, nothing is transferred to 
the library file. 


If the line contains a semicolon embedded in noncomment text and 
you want comments squeezed, code a dummy comment for that line. 
The /SZ switch will use only the rightmost comment during squeeze 
processing. | 


Example 


Figure 7-14 illustrates the use of the LBR /SZ switch. A 
file containing input text to be squeezed is illustrated, 
along with the text actually inserted into the library file 
after the squeeze operation has been completed. 
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BEFORE 
~-MACRO MOVSTR RX,RY,?LBL 


= = “NOTE 
BOTH ARGUMENTS MUST BE REGISTERS 


MOVB (RX)+, (RY) + ;MOVE A CHARACTER 


BNE LBL ;CONTINUE UNTIL NULL SEEN 
DEC RY ;BACKUP OUTPUT PTR TO NULL 


MOVSTR 
- ENDM 


AFTER 


~-MACRO MOVSTR RX,RY,?LBL 
Sone NOTE: 

BOTH ARGUMENTS MUST BE REGISTERS 
MOVB (RX)+, (RY) + 

BNE LBL 

DEC RY 

- ENDM 


ZK-197-81 


Figure 7-14: MACRO Listing Before and After Running LBR with /SZ 


7.6 COMBINING LIBRARY FUNCTIONS 


Two or more library functions may be requested in the same 
command line. The only exceptions are that /CO cannot be 
requested with anything else except /LI, and /CR and /DE cannot 
be specified in the same command line. 


Functions are performed in the following order: 


1. Default switch (/DF) 

2. Create switch (/CR) 

3. Delete switch (/DE) 

4, Delete Global switch (/DG) 

5. Modify Header switch (/MH) 

6. Insert (/IN), Replace (/RP), Selective Search (/SS), 
Squeeze (/SZ), Entry Point (/EP) switches 

7. Compress switch (/CO) 

8. Extract switch (/EX) 

9s List Switches: (/L1 >. ~EE, FU) 


COMBINING LIBRARY FUNCTIONS 


Example 
LBR>FILE/DE:XYZ:SA,FILE.LST: /LE/FU=MODX , MODY /RP 
Functions, performed in order, are: 

1. Delete modules XYZ and SA. 


2. Insert all modules from MODX and replace duplicate 
modules of MODY. 


3. Produce a listing of the resultant library file on 


the line printer with full module descriptions and 
all entry points. 


7.7 LBR ERROR MESSAGES 
LBR returns two types of error messages: diagnostic and fatal. 
Diagnostic error messages describe a condition that requires 
consideration, but the nature of the condition does not warrant 
termination of the command. Diagnostic messages are issued to 
your terminal screen in the format: 

LBR -- *DIAG* - message 
Fatal error messages describe a condition that caused LBR_ to 
terminate the processing of a command. When this occurs, LBR 
returns to the highest level of command input. For example, LBR 
issues the fatal error message and exits if you enter the 
command: 

S RUN SLBR/COMMAND:"LBR cmd" 


where cmd is an LBR command. 


If, however, you enter the command in response to the LBR prompt, 
Chat 2S; 


LBR>cmd 
LBR issues the fatal error message and reprompts. 


Fatal error messages are issued to your terminal screen in the 
LOormat: 


LBR ERROR MESSAGES 


LBR -- *FATAL* - message 


If a fatal error occurs during the processing of an indirect 
command file, the command file is closed, the fatal error 
message--followed by the command line in error---is issued to 
your terminal screen and LBR_ returns to the highest level of 
command input. 


7.7.1 Effect of Fatal Errors on Library Files 
The status of a library file after fatal errors is: 


1. In general, output errors leave the library in an 
indeterminate state. 


2. During the deletion process, the library is rewritten 
prior to the printing OL the individual 
module-/entry-point-deleted messages. 

3. During the replacement process, the library is rewritten 
prior to the printing of the individual module-replaced 
messages. 

4. During the insertion process, the library is rewritten 


after the insertion of all modules in each individual 
input file, that is, between input files. 


7.7.2 LBR Error Messages 


LBR -- BAD LIBRARY HEADER 


Explanation: The file is not a library file or it is 
corrupted. 


User Action: 


@ If the file is not a library file, reenter the command 
line with a proper library file specified. 


° If the file is a proper library file, the volume may be 
corrupted. 
& If the volume is corrupted, it must be reconstructed 


before it can be used. 


LBR ERROR MESSAGES 


LBR -- CANNOT MODIFY HEADER 
Explanation: An attempt was made to modify the module 
header of a module in an object library or macro library. 
No change is made to the module header. 
User Action: Reenter the command line, Specifying a module 
in a universal library. 

LBR -- COMMAND I/O ERROR 
Explanations: One of the following conditions may exist: 


@ A problem exists on the physical device. 


© The file is corrupted or the format is incorrect (for 
example, record length exceeds 132 bytes). 


User Actions Determine which of the conditions caused the 
message and correct that condition. Reenter the command 
line. 


LBR -- COMMAND SYNTAX ERROR 
command line 


Explanation: A command was entered in a format that does 
not conform to syntax rules. 


User Actions: Reenter the command line, uSing the correct 
syntax. 
LBR -- DUPLICATE ENTRY POINT NAME "name" IN filename 


Explanation: An attempt was made to insert a module into a 
library file when both contain an identically named entry 


point. 

User Action: Determine if the specified input file is the 
correct file. If not, reenter the command line, specifying 
the correct input file. If the input file is the correct 


file, you can delete the duplicate entry point from the 
library and reenter the command line. 
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LBR -- DUPLICATE MODULE NAME "name" IN filename 


Explanation: An attempt was made to insert (without 
replacing) a module into a library that already contains a 
module with the specified name. 


User Actions Determine if the specified input file is the 
correct file. If the input file is correct, decide whether 
to delete the duplicate module from the library file and 
insert the new one, or replace the duplicate module with the 
/RP switch appended to the input file specification. 


LBR -- EPT OR MNT EXCEEDED IN filename 


Explanation: The EPT or MNT table limit was reached during 
the execution of an insert or replace operation. 


User Action: Copy the library, increasing the table space 
by means of the Compress switch. Reenter the command line. 


LBR -- EPT OR MNT SPACE EXCEEDED IN COMPRESS 


Explanations: An EPT or MNT table size was specified for the 
output library file that is not large enough to contain the 
EPT or MNT entries used in the input library file. 


User Action: Reenter the command line with a larger EPT or 
MNT table size specified. 


LBR -- ERROR IN LIBRARY TABLES, FILE filename 


Explanation: The library file is corrupted or is not a 
Library Fite. 


User Action: If the file is corrupted, no recovery 1s 
possible; the file must be reconstructed. If the file is 
not a library file, reenter the command line with the 
correct library file specified. 


LBR -- EXACTLY ONE INPUT FILE MUST APPEAR WITH /CO 


Explanation: No input library file, or more than one file, 
was specified when using the /CO switch. 


User Action: Reenter the command line with only one input 
file specified. 
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LBR => PATAL GOMPRESS ERROR 


Explanations The input library file is corrupted or is not 
a Library fie. 


User Action: No recovery is possible. The file in question 
must be reconstructed. 


LBR os GET TIME -PAILED 


Explanations This error occurs when LBR attempts to execute 
a Get Time Parameters directive and fails. The error is 
caused by a system malfunction. 


User Action: Reenter the command line. If the problem 
persists, call your DIGITAL Customer Support Center. 


LBR -- ILLEGAL DEVICE/VOLUME 
command line 


Explanation: The Device specifier entered does not conform 
to syntax rules. A device specifier consists of two ASCII 
characters, followed by one or two optional octal digits. 


User Action: Reenter the command line with the correct 
device syntax specified and followed by a colon. 


LBR -- ILLEGAL DIRECTORY 
command line 


Explanation: The directory entered does not conform to 
syntax rules. Directory syntax consists of a left square 
bracket, followed by one to nine alphanumeric characters (or 
one to three octal digits, a comma, and one to three octal 
digits), terminated by a right square bracket (for example, 
[USERFILES]). 


User Action: Reenter the command line with the correct 
directory syntax. 

LBR -- ILLEGAL FILENAME 

command line 


Explanation: One of the following was entered: 


® A file specifier that: contains: -a wildcard. 
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) A file specifier that contains neither a file name nor a 
file type. 


User Actions Reenter the command line correctly. 


LBR -- ILLEGAL GET COMMAND LINE ERROR CODE 
Explanations LBR could not process the command line. 


User Actions Reenter the command line. If the problem 
persists, call your DIGITAL Customer Support Center. 


LBR -- ILLEGAL SWITCH 
command line 


Explanation: A non-LBR switch was specified or a legal 
Switch was specified in an invalid context. 


User Action: Reenter the command line with the correct 
Switch specification. 


LBR -- ILLEGAL SWITCH COMBINATION 


Explanation: Switches were entered that cannot be executed 
in combination. See Section 7.6. 


User Action: Reenter the command line, specifying the 
Switches in the proper combination. 


LBR -- INDIRECT COMMAND SYNTAX ERROR 
command line 


Explanations: An indirect command file was specified in a 
format that does not conform to syntax rules. 


User Actions: Reenter the command line with the correct 
syntax. 


LBR -- INDIRECT FILE DEPTH EXCEEDED 
command line 


Explanation: An attempt was made to exceed one level of 
indirect command files. 


User Actions Rerun the job with only one level of indirect 
command file specified. 


LBR ERROR MESSAGES 

LBR -- INDIRECT FILE OPEN FAILURE 

command line 
Explanation: The requested indirect command file does not 
exist as specified. One of the following conditions may 
exist: 
) The user directory area is protected against access. 
e A problem exists on the physical device. 
) The volume is not mounted. 
@ The specified file directory does not exist. 
@ The file does not exist as specified. 
e Insufficient dynamic memory exists in the Executive. 
User Action: Determine which of the conditions caused _ the 
message and correct that condition. Reenter the command 
line. 


LBR -- INPUT ERROR ON filename 


Explanation: The file system, while attempting to process 
an input file, has detected an error. 


A problem exists with the physical device. 


User Action: Reenter the command line. 


LBR -- INSUFFICIENT DYNAMIC MEMORY TO CONTINUE 


Explanation: Your library is too large for the attempted 
operation. 


User Action: Break up the library into two or three smaller 
libraries. 
LBR -- INVALID EPT AND/OR MNT SPECIFICATION 


Explanation: An EPT or MNT value greater’ than 4096 
(decimal) was entered in a /CR or /CO switch. 


User Action: Reenter the command line with the correct 
value specified. 
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LBR -- INVALID FORMAT, INPUT FILE filename 


Explanations The format of the specified input file is not 
the standard format for a macro source or object file, or 
the input file is corrupted. 


User Action: Reenter the command line with the correct 
input file specified. 


LBR = DNVAGID: DIBRARY “TYPE: SPHCIRIED 


Explanation: An invalid library type was specified when 
using the Create or Default switch. The values OBJ, MAC, 
and UNI are the only valid specifications. See Sections 
Teoe2 and. (54 


User Actions: Reenter the command line with OBJ, MAC, or UNI 
specified. 


LBR -- INVALID MODULE FORMAT in insertion module 


Explanation: An attempt was made to insert a macro module 
into an object library. 


User Actions Determine if an object file was to be inserted 
into an object library. If so, reenter the command line 
with the correct object file. If a macro library was’ to 
receive the insertion, reenter the command line with the 
correct macro library. 


LBR -- INVALID NAME -- "name" 


Explanation: A module name that contains a non-Radix-50 
character was specified for deletion, insertion, or 
replacement of a module ina universal library or in a macro 
module; or a module name was specified for modification of a 


universal module header. Radix-50 characters consist of the 
letters A through 2Z, the numbers 0Q through 9, and the 
special characters period (.) and dollar sign (S$). 


User Action: Reenter the command line with a valid name. 
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LBR -- INVALID OPERATION FOR OBJECT AND MACRO LIBRARIES 
Explanation: Module header information was supplied for an 
object library or macro library in an insert or replace 


operation. 


User Action: No action required. The command will be 
executed as if the information had not been supplied. 


LBR -- INVALID RAD50 CHARACTER IN "character string" 
Explanation: A character supplied as part of information 
when using the Insert, Replace, or Modify Header switches 
for a universal library is not a Radix-50 character. 
User Actions Determine which character of the corresponding 
Switch value is not a Radix-50 character. Reenter a 
Radix-50 character in place of the invalid character. 


LBR -- I/O ERROR ON INPUT FILE filename 


Explanation: A read error has occurred on an input file. 
One of the following conditions may exist: 


8 A problem exists on the physical device. 


) The file is corrupted or the format is wrong (record 
length exceeds 132 bytes). 


User Action: Determine which of the conditions caused the 


message and correct that condition. Reenter the command 
line. 
LBR -- LIBRARY FILE SPECIFICATION MISSING 


Explanation: A command line was entered without specifying 
the library file. 


User Action: Reenter the command line with the library file 


specified. 
LBR -- MARK FOR DELETE FAILURE ON LBR WORK FILE 
Explanation: When LBR begins processing commands, 1% 


automatically creates a work file and marks it for delete. 
For some reason, this marking for delete failed. 
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The work file constitutes a lost file because it does not 
appear in any file directory. 


User Action: The file may be deleted by typing the 
following command from the DCL command level: 


S @VERIFY 
LBR -- MULTIPLE MODULE EXTRACTIONS NOT PERMITTED FOR UNI MODULES 


Explanations An attempt was made to extract more than one 
module from a universal library. The first module specified 
is extracted, but others are ignored. 


User Action: Reenter the command line for each additional 
extraction. 


LBR -- NO ENTRY POINT NAMED "name" 


Explanation: The entry point to be deleted is not in the 
specified library file. 


User Action: Determine if the entry point is misspelled or 
if the wrong library file is specified. Reenter the command 


line with the entry point or the library file correctly 
specified. 


LBR -- NO MODULE NAMED "module" 


Explanation: The module to be deleted is not in the 
specified library file. 


User Action: Determine if the module name is misspelled or 


if the wrong library file is specified. Reenter the command 
line with the module name correctly specified. 


LBR -- OPEN FAILURE ON FILE filename 
Explanation: The file system, while attempting to open a 
rite: has detected an error. One of the following 


conditions may exist: 


cy The user directory area iS protected against an open 
operation. 


© A problem exists on the physical device. 
~) The volume is not mounted. 


@ The specified file directory does not exist. 
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The file does not exist as specified. 


Insufficient contiguous space to allocate the library 
file (Compress and Create only). 


Insufficient dynamic memory exists in the Executive. 


User Actions: Determine which of the above conditions caused 


the 


message and correct that condition. Reenter that 


command line. 


LBR -- OPEN FAILURE ON LBR WORK FILE 


Explanation: The file system, while attempting to open the 
LBR work file, has detected an error. The LBR work file is 
created on the volume from which LBR was installed. One of 
the following conditions may exist: 


The volume is full. 
The device is write-protected. 
A problem exists with the physical device. 


Insufficient dynamic memory exists in the Executive. 


User Action: Determine which of the conditions caused the 


message and correct that condition. Reenter the command 
line. 
LBR -- OUTPUT ERROR ON filename 


Explanation: A write error has occurred on the output file. 
One of the following conditions may exist: 


8 


The volume is full. 
The device is write-protected. 


The hardware has failed. 


User Action: If the volume is full, delete all unnecessary 


files and rerun LBR. If the device is write-protected, 
write-enable the device and reenter the command line. ea 
the hardware has failed, swap devices and reenter the 


command line or wait until the device is repaired and rerun 


LBR. 
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LBR -- POSITIONING ERROR ON filename 


Explanation: A positioning error has occurred on the input 
file. One of the following conditions exist: 


© A problem exists on the physical device. 


@ The file is corrupted or the format is wrong. 


User Action: Determine which of the conditions caused the 


message and correct that condition. Reenter the command 
line. 
LBR -- RMS MODULES CANNOT BE EXTRACTED TO RECORD ORIENTED DEVICES 


Explanation: An attempt was made to extract a module 
inserted from a nonsequential RMS file to a record-oriented 
device. This is a fatal error message. 


User Actions Extract the file to a disk and then use an RMS 
conversion to make an RMS sequential file. 


LBR -- TOO MANY OUTPUT FILES SPECIFIED 


Explanations: More than two output files were specified. 
LBR makes the following assumptions: 


@ The first output file specified is -the output library 
bes 


@ The second output file specified is the listing file. 


7) The third ‘through: n. files specified to. the bert. of the 
equal sign are ignored. 


User Action: No action is required. LBR continues as 
though. the extra file(s) had not been specitied. 


LBR -- VIRTUAL STORAGE REQUIREMENT EXCEEDS 65536 WORDS 


Explanation: This error may occur if you are working with 
maximum size libraries. You might have specified a single 
command line that first logically deletes a large number of 
modules and entry points, then replaces them with an equally 


large number of modules and entry points. The replacement 
modules and entry points have names much different from 
those being replaced. This message usually indicates a 
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system error. 

User Action: Rerun the job, but divide the complicated 
command line into several smaller command lines that do the 
same operations. 


LBR -- WORK FILE I/O ERROR 


Explanation: A write error has occurred on the LBR_ work 
file. One of the following conditions may exist: 


@ The volume is full. 

a The device is write-protected. 

® The hardware has failed. 

User Action: If the volume is full, delete all unnecessary 
files and rerun LBR. If the device is write-protected, 
write-enable the device and reenter the command line. bie a 


the hardware has failed, swap devices and retry the command, 
or wait until the device is repaired and rerun LBR. 


CHAPTER 8 
RESOURCE MONITORING DISPLAY (RMD) 


The Resource Monitoring Display (RMD) is a privileged task that 
displays information about the resources in your system. This 
information includes the active tasks, their location in memory, 
the amount of memory they occupy, and available pool space. 


8.1 INTRODUCTION 


RMD consists of pages. A page consists of 24 lines. The program 
contains two kinds of pages: display and setup. 


8.1.1 Display Pages 
There are four display pages available: 
@ Memory (M) 
® Active Task List (A) 
e Task Header (T) 
@ Help (H) 


You press the terminal keys indicated in parentheses to switch 
display pages. 


8.1.2 Setup Pages 
There are three setup pages. Each setup page is associated with 


a display page. (The Help Display Page has no associated setup 
page.) You access a setup page from a display page by pressing 


ore 


ENT RODUCTION 


the CTRL-[ sequence on your terminal. The setup page documents 
and prompts you for setup commands, which alter the content of 
the information displayed on the associated display page. 


8.2 INVOKING RMD 


You can invoke RMD in three ways: 


1. Invoke the SHOW MEMORY command, which in turn invokes’ RMD. 
See Chapter 3 for a description of the SHOW MEMORY command. 


2. Invoke the SHOW TASKS/DYNAMIC command, which in turn invokes 
RMD. See Chapter 3 for a description of the SHOW 
TASKS/DYNAMIC command. 


3. Invoke RMD directly from the DCL command level. 


To invoke RMD directly from the DCL command level, enter the 
following command: 


S RUN SRMD 
After entering the command, you see the memory display page on 


your terminal screen, indicating that you are in the RMD 
environment. Once you are in the RMD environment, RMD waits’ for 


your command. 


RMD accepts command lines in the following general format: 


([page][,setupcommand] 

page 
One of the display page abbreviations (M, A, T, or H). The 
default page is the Memory Display (M). 

setupcommand 


A valid setup command for the display page that you have 
selected. The setup commands are the same as_ those 
available to you from the setup page associated with the 
display page you specified. The default setup commands are 
discussed in Sections 8.4 through 8.6, which describe the 
content of each display page and how you use setup commands 
to alter display parameters. 


INVOKING RMD 


8.2.1 Running RMD on a Second Terminal 


You can connect a second terminal to the Professional through its 
printer port. (For details, see the section on debugging an 
application in the Tool Kit User’s Guide). 


Enter the following commands, either from the keyboard or from an 
indirect command procedure: 


S SET TERMINAL /TT2: /NOSLAVE 
S ASSIGN/TASK RMD TT2: it 
S ASSIGN/TASK RMD TT2: 2 
S$ SPAWN SHOW MEMORY 


This command sequence does the following: 


® It reassigns LUNs 1 and 2 to the terminal on which you want 
to run the task, and 


® It invokes the task on the second terminal while allowing you 
to continue entering DCL commands at the Professional’s 
terminal. 


NOTE 


You must be a privileged user to issue the SET 
TERMINAL /TT2: command. 


8.3 THE HELP DISPLAY 


The Help Display documents how you switch display pages. You 
Switch display pages by pressing a terminal key as follows: 


Key Explanation 


M Accesses the Memory Display 
A Accesses the Active Task Display 
T Accesses the Task Header Display 


The Help Display also documents how to exit from RMD and use the 
CTRL-[ sequence to access setup pages from their associated 
display pages. (Because there is nothing to alter on the Help 
Display, no setup page is available from the Help Display.) 


The Memory, Active Task, and Task Header Displays use the entire 
screen. Therefore, you receive no prompts or documentation on 
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display pages. To find out how to access a setup page from a 
display page or how to switch display pages, press the H key (for 
Help) to access the Help Display. 


8.4 THE MEMORY DISPLAY 


The Memory Display graphically represents system memory. Lt 
Shows the approximate size and locations of partitions and active 
tasks, pool statistics, the name of the currently-executing task, 
and other information regarding operating system status. You 
access the Memory Display from another display page by pressing 
the M key (for Memory). If you invoke RMD without specifying a 
display page, RMD defaults to the Memory Display. 


Figure 8-1 shows the Memory Display. See the numbered notes 
following the figure for a description of each item in the Memory 
Display. 
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Figure 8-1: Memory Display for P/OS 
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Notes to Figure 8-1 


Operating system type, version number, and base level. 


A one- to six-character name that is a DECnet node name (if 
DECnet iS running on your system). 


Size in K words of the system memory. 


Time elapsed in units of days, hours, and minutes, since the 
system was last booted. 


Current date and time. 


Name of the task that is currently executing or, if none is 
executing, *IDLE* (Executive executing the idle loop). 


Number of free blocks on the first four FILES-11 devices in 
your system. If a device is dismounted, RMD displays: 
"DMO". If a device is off line, RMD displays: "OFL". 


Pool (dynamic storage region) information in the format: 


POOL=X: ¥:24 
» 4 

Number of words in the largest free block in pool 
Y¥ 

Number of free words in pool 
Z 


Number of fragments in the pool free list 
The second line records the worst case of pool since you 
invoked RMD. This line is most useful if RMD has been 
running on a second terminal since the last system boot. 


Secondary pool information in the format: 


SECPOOL=A:B:C% 


Number of free blocks in secondary pool 


Total number of blocks in secondary pool 
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Percentage of secondary pool that is free 


The second line records the worst case of secondary pool 
Since you invoked RMD. This line is most useful if RMD has 
been running on another terminal since the last system boot. 
Partitions in the system using the format: 
partitionname:type 
type 
One of the following: 


D System-controlled (dynamic) partition 
P Secondary pool partition 


Number of tasks in memory and amount of memory they use, and 
number of active tasks swapped or checkpointed out of memory 
and the amount of memory they would require. 


Name of each task, common, or driver in memory and its 
location in memory using the following symbols to designate 


Size, type (task, common, or driver), and other attributes: 
Symbol Attribute 
4 > Active task 


[ ] Task not active, yet occupies memory 

! ! Named common : 

. “ Unnamed common (displayed name is first 
attached task) 

( ) Loaded driver using device mnemonic 

~---- Task not fixed in memory 

=== Task fixed in memory 


The hyphens and equal signs represent the amount of memory 
that each task, driver, or common occupies. Where the 
display shows only one delimiter and no hyphens or equal 
signs, the open delimiter is in the same location as the 
closing delimiter of the preceding task. 


Partition sige and location. The beginning of eacn 
partition is marked with the same symbols as those listed 
previously, plus the following additions: 
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E Executive 
P Pool 


The lines of asterisks are proportional representations of 
the amount of memory occupied by each partition. The 
numbers are in 1K word increments. Each numerical character 
also represents the same amount of memory as an asterisk. 
RMD always divides the system memory into groups of eight 
units. 


(14) System error count sequence recorded by the Error Logger 
(always zero if Error Logger not present in your system). 


8.4.1. Altering the Memory Display from the Setup Page 


To alter the Memory Display, you press the CTRL-[ sequence, which 
accesses the setup page for the Memory Display. The setup page 
documents and prompts you for commands which you use to alter the 
Memory Display. You can enter multiple commands after each 
prompt by using commas as _ separators. The setup commands 
available for altering the Memory Display are: 


® FREEx=ddnn: where x is a number from 0 to 3 and ddnn: is a 
device name and number 


® RATE=s where s is the replot rate in seconds 


You can truncate these commands to their shortest unique forms. 
These setup parameters stay in effect until you alter them, even 
if you switch to another display page and back to the Memory 
Display. 


8.4.1.1 The FREE Command - You use this command to determine the 
four FILES-11 devices for which you want the Memory Display to 
show the available free blocks. This. 2nformation aS. (7) an 
Figure. 61. The default is your system disk (SY:) and the next 
three FILES-11 devices in your configuration. 


8.4.1.2 The RATE Command - You use this command to determine how 
often RMD replots the Memory Display. The default replot rate is 
once per second. 
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8.5 THE ACTIVE TASK DISPLAY 

The Active Task Display shows you the active tasks in the system. 
You access this display from another display page by pressing the 
A key (for Active Task). 

This display has six fields: 

® Name of the task 

@ Length of the task in octal bytes 

® Terminal that issued the task 

@ Running priority of the task 

6 Outstanding I/O count 


® Status flags 


The status flags use the same mnemonics as the SHOW TASK/FULL 
command. See Chapter 3 for definitions of the status flags. 


8.5.1 Altering the Active Task Display from the Setup Page 


To alter the Active Task Display, you press the CTRL-[ sequence, 
which displays the setup page for the Active Task Display. The 
setup page documents and prompts you for commands that you use to 
alter the Active Task Display. You can enter multiple commands 
after each prompt by using commas as _ separators. The setup 
commands available for altering the Active Task Display are: 


® OWNER=ttnn: where ttnn: is the terminal that issued the 
task 


@© PRIORITY=p where p is a task’s running priority 
® RATE=s where s is the replot rate in seconds 
e TASK=taskname where taskname is the name of the task whose 


header you want to display 


You can truncate these commands to their shortest unique forms. 
These setup parameters stay in effect until you alter them, even 
if you switch to another display page and back to the Active Task 
Display. 
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8.5.1.1 The OWNER Command - This command allows RMD to display 
only those tasks that have been issued by a particular terminal. 
The default is ALL, which displays tasks issued from all 
terminals. 


8.5.1.2 The PRIORITY Command - The active task list may be too 
long to fit on one screen. You use the PRIORITY command to 
determine the highest priority tasks that you want to see. The 
default is 250, the highest possible priority. 


8.5.1.3 The RATE Command - This command allows you to determine 
how often RMD replots the Active Task Display. The default 
replot rate is once per second. 


8.5.1.4 The TASK Command - This command allows you to look at a 
specific task header. This command is an exception because it 18 
the only setup command that switches display pages. There is no 
default for the TASK command. The Task Header Display is 
discussed in Section 8.6. 


8.6 THE TASK HEADER DISPLAY 
The Task Header Display shows you the task header of the task you 
specify. You access this display from another display page by 
pressing the T key (for Task Header). If no task is currently 
specified, RMD shows you the setup page first so that you can 
specify the task whose task header you want RMD to display. 


The Task Header Display shows you the following information about 
the specified task: 


@ Name of the task 
e Name of the partition in which the task runs 


© Status flags, which have the same mnemonics as in the Active 
Task display 


® Owner of the task by terminal number 
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@® Outstanding I/O count 

6 Derault prigrity 

® Running priority 

® Swapping priority 

@ Length in decimal words 


@ Contents of the six general purpose registers, the program 
counter, and the Processor Status Word 


® Contents of the Directive Status Word (SDSW) 
6 Local event flags 


® Logical unit number (LUN) assignments to a maximum of 26 LUNs 


When RMD displays file names in the list of LUN assignments, the 
filename and directory displayed are the filename and directory 
of the file when it was created. If the file has been renamed, 
the RMD display may not reflect the current directory and/or 
Filename. 


8.6.1 Altering the Task Header Display from the Setup Page 


To alter the Task Header Display, you press the CTRL-[ sequence, 
which displays the setup page for the Task Header Display. The 
setup page documents and prompts you for commands that alter the 
Task Header Display. You can enter multiple commands after each 
prompt by using commas as separators. The setup commands 
available for altering the Task Header Display are: 


® RATE=s where s is the replot rate in seconds 


® TASK=taskname where taskname is the name of the task whose 
header you want to display 


You can truncate these commands to their shortest unique forms. 
These setup parameters remain in effect until you alter then, 
even if you switch to another display page and back to the Task 
Header Display. 
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8.6.1.1 The RATE Command - This command allows you to determine 
how often RMD replots the Task Header Display. The default 
replot rate is once per second. 


8.6.1.2 The TASK Command - This command changes the task header 
to be displayed. There is no default. The TASK command has the 
same function as the TASK command on the Active Task Display, 
except that here it does not switch display pages. 


8.7 ERROR MESSAGES 


RMD generates the following error messages: 


RMD - Allocated screen buffer too small for this device 
Explanation: RMD requires more internal memory to display 
the requested display on the type of terminal on which you 


are running RMD. 


User Action: Call your DIGITAL Customer Support Center. 


RMD - Illegal command - xxxxx 
Explanation: You entered an illegal command xxxxx either on 
the command line or in response to the COMMAND> prompt ona 
Setup. page. 
User Actions Enter the correct command as documented in 
this chapter. 


RMD - Page does not exist 


Explanation: You requested a display page from the command 
line that does not exist. 


User Action: Enter the command line again specifying a 
correct display mnemonic. 
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RMD: = SeCqGmMent. “XEXRXX” NOt found 
Explanations: The module xxxxxx was not found in the task 
image for RMD. This denotes an error in how RMD was 
task-built. 
User Action: Call your DIGITAL Customer Support Center. 


RMD - Terminal type not defined 


Explanation: The operating system and RMD do not recognize 
your terminal type. 


User Action: Check your terminal type using the command 


SHOW TERMINAL. If this setting is incorrect, use the SET 
TERMINAL command to correct your terminal type setting. 


RMD - Terminal type not set 
Explanations You did not build RMD to display the requested 
display page on the type of terminal to which your terminal 
is set. 


User Action: Determine your terminal type setting using the 


command SHOW TERMINAL. If this setting is incorrect, use 
the command SET TERMINAL to correct your terminal type 
setting. 


RMD - Terminal type not yet supported 
Explanations RMD does not recognize your terminal type. 


User Action: Determine your terminal type setting using the 


command SHOW TERMINAL. If this setting is incorrect, use 
the command SET TERMINAL to correct your terminal type 
setting. 


CHAPTER 9 
TASK/FILE PATCH PROGRAM (ZAP) 


The Task/File Patch Program (ZAP) allows you to directly examine 
and modify task image and data files on a FILES-11 volume. Using 


ZAP, you can patch these files interactively without reassembling 
and rebuilding the task. 


ZAP supports four types of task image files: 


® Regular task image files, which include those mapped to 
resident and supervisor mode libraries 


@ Multiuser task image files 


@ I- and D-space (instruction and data space) tasks 


® Resident libraries 


NOTE 


I- and D-space and supervisor mode libraries are 
not currently supported. 


These types of task image files are discussed fully with the 
/uist switch (refer to Section 9.1). 


ZAP performs many of the functions performed by the RSxX-11 
on-line debugging utility, ODT. Thus, working knowledge of ODT 


is helpful in using ZAP. See the IAS/RSX-11 ODT Reference Manual 
for more information on ODT. 


ZAP provides the following features: 


@® Operating modes that allow you to access specific words’ and 
bytes im a file, modify Tocations in a fiie, 11st the disk 
block and address boundaries for each overlay segment in a 
task image file on disk, and open a file for reading only. 


@ A set of internal registers that include eight Relocation 
Registers. 


© Single-character commands that, with other command line 
elements, allow you to open and close locations in a file and 
to display and manipulate the values in those locations. 


Although the ZAP program is relatively straightforward to _ use, 
patching locations ina task image file requires knowing how to 
use the map (or memory allocation file) generated by the Task 
Builder and the listings generated by the MACRO-11 
assembler. These maps and listings provide information you need 
to access. the locations whose contents you want to change. For 
information on Task Builder maps, see the RSX-11M/M-PLUS and 
Micro/RSX Task Builder Manual. For information on MACRO-1i1 
listings, see the PDP-11 MACRO-11 Language Reference Manual. 


9.1 ZAP OPERATING MODES AND SWITCHES 


ZAP provides two addressing modes and two access modes. The 
addressing modes are task image mode and absolute mode. Task 
image mode is the default mode. The access modes are read/write 
mode and read-only mode. Read/write is the default mode. Either 
addressing mode can be used with either access mode. The modes 
and their associated switches are as follows: 


@e Task image mode is the default addressing mode for ZAP. In 
this mode, addresses in ZAP command lines refer to addresses 
in the task image file as they are shown in the Task Builder 
map for the file. Refer to Section 9.1.1.1 for more 
information on using task image mode. 


® In absolute mode, specified with the /AB- switch, ZAP 
processes the addresses you enter in ZAP command lines as 
absolute byte addresses within the file. You must use 
absolute mode for any files that are not task images. Refer 
to Section 9.2.1 for more information on using absolute mode. 


® Read/write mode is the default access mode for ZAP. In this 
mode, ZAP opens a file for reading and/or modification. 


® In read-only mode, specified with the /RO switch, ZAP opens a 
Fite for reading “but Mol moditication.; That 2s, ‘you: can 
execute ZAP functions that change the contents of lJlocations, 
but these changes are not actually made to the file. When 
ZAP exits, the original values in the file are still there. 
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9.1.1. The List Switch (/LI) 


When using ZAP in task image mode (but not absolute), you can 
also specify the /List switch (/LI). The /List switch displays 
the overlay segment table for the on-disk task image file with 
which you are working. The table lists the Starting disk block 
and address boundaries for each overlay segment in the file. The 
segment table lists are ina different format for each type of 
task image file. The table and Task Builder map allow you to 
locate the task segments being changed. 


The /LI switch displays the overlay segment boundaries in the 
following format: 


SSSSSS: aaaaaa-bbbbbb [nnnnnn] [dddddd] 

SSSSSS3 

ine: starting block in octal: 
aaaaaa 

The lower address boundary in octal. 
bbbbbb 

The upper address boundary in octal. 
nnnnnn 


The segment name that appears for I- and D-space tasks; 
manually loaded overlays (SLOAD); memory-resident overlays; 
tasks that link to the library with memory-resident 
overlays; or for any combination of the previous conditions. 


dddddd 


The description of the segment type string which appears 
next to the segment name in the segment table. 


The following sections describe the /List switch formats for’ the 
different kinds of task image files. Section. “9.646 Gives 
examples of the segment table lists. 


9.1.1.1 The /LI Switch and Regular Task Image Files - For 
regular task image files, including those mapped to resident and 
supervisor mode libraries, the /LI switch displays the task’s 
overlay segments in the order of their location in the file. 
Fach segment begins on an even block boundary. 


eae 
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9.1.1.2 The /LI Switch and Multiuser Task Image Files - For 
multiuser tasks, the /LI switch lists the starting disk block 
number and address boundaries of each segment. In addition, the 
address boundaries of the shared read-only segment are listed. 
The block number that is used to reference the multiuser segment 
is the same as the root segment. The multiuser segment is an 
extension of the root segment. The segment list disk block 
numbers have a corresponding entry in the Task Builder map. 


See the RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for more 
information on multiuser tasks. 


9.1.1.3 The /LI Switch and Resident Libraries - For 
resident libraries, the /LI switch displays each of the task’s 
segments as beginning on a new block boundary. However, the 
segments may not actually begin on even boundaries because of 
compression by the Task Builder. Resident libraries can _ be 
overlaid, but each overlay segment must also be resident in 
memory. | 


To avoid the possibility that two or more segments in a= single 
block could have the same virtual address, ZAP treats the 
resident library in the same way that the Task Builder does. The 
Task Builder builds the library with each segment beginning on an 
even block boundary, but then compresses the segments in the task 


file itself. The Task Builder map is generated before the 
segments are compressed, so the boundaries given in the map _ do 
not necessarily correspond to the actual location of the 
segments. 


The disk block boundaries given in the Task Builder map file are 
the ones that ZAP uses to address locations in the resident 
library and that the /LI switch displays in its segment table. 


They do not use the actual starting blocks of the segments. (You 
should be aware of this when you are working with resident 
libraries in absolute mode. However, also remember that you 


cannot use the /LI switch in absolute mode.) 


You should also note that ZAP cannot know the physical starting 
addresses for the segments of an overlaid resident library 
because its overlay structure is stored in the symbol definition 
(.STB) file, not with the task image file itself. For ZAP, each 
segment’s starting address is Q00Q000Q0. 


See the RSX-11M/M-PLUS and Micro/RSX Task Builder Manual for more 
information on resident libraries. 
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9.1.1.4 The /LI Switch and I- and D-Space Tasks - For I- and 
D-space tasks, the /LI switch lists the starting block number and 
the address boundaries of each segment. The I-space or D-space 
segment may be suppressed in the listing when, for example, a 
segment with only I-space code does not include a listing for a 
D-space segment. If the segments are not suppressed, the segment 
list disk block numbers have a corresponding entry in the _ Task 
Builder map. 


9.2 ADDRESSING LOCATIONS IN FILES 


To address locations ina file, ZAP provides two addressing modes 
(task image and absolute, described above) and a set of internal 
registers, which includes eight Relocation Registers. This 
section first introduces the concept of relocation biases and the 
use of the Relocation Registers, then explains how to use the 
addressing modes. 


9.2.1 Relocation Biases 


When MACRO-11 generates a relocatable object module, the base 
address of each program section of the module is 000000. In the 
assembler listing, all locations in the program section are shown 
relative to this base address. 


The Task Builder links program sections to other program sections 
by mapping the relative addresses applied by the assembler to the 
physical addresses in memory (for unmapped systems) or to virtual 
addresses (for mapped systems). 


Many values within the resulting task image are biased by a 
constant whose value is the absolute base address of the program 
section after the section has been relocated. This bias 1s 
called the relocation bias for the program section. 


ZAP’s eight Relocation Registers, OR through 7R, are generally 
set to the relocation biases of the program sections to be 
examined. This allows you to refer to a location in a module by 
the same relative address that appears in the MACRO-11 listing. 
The addressing modes help you calculate the relocation biases. 


9.2.2 ZAP Addressing Modes 


As explained in Section 9.1, ZAP’s two modes for addressing 
locations ina file are task image mode and absolute mode. Task 


cas) 
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image mode is the default mode for ZAP. 


explain how to use these modes. 


The following examples show excerpts from a MACRO-11 
the module MYFILE and a Task Builder map. 
accompanying text show how to use ZAP in task 


following lines represent assembled instructions from a MACRO-11 


source listing: 


The 


next two sections 


basting Cf 
These excerpts and the 
image mode. The 


7000574 032767 Q00000G 000000G BIT #FE.MUP,SFMASK 

72 000602 001002 BNE 25S 

73 000604 000167 000406 JMP 30S 

74 000610 016700 000000G Zo, MOV. “STRICE RO 

75 000614 016000 000000G MOV T.UCB(RO),RO 

76 000620 CLOG) LP saq MOV RQ,UCB 

77 000624 032760 000000G 000000G BIT #U2.HLD,U.CW2(RO0) 


The following lines from a Task Builder map give the information 
you need to address locations in the task image file as they 
appear in the above MACRO-11 listing: 


T20000- 123023 CO3024 01556. 
000002 000005 000004 00004. 


Lee Ts 
LIM TS? 


R/W MEM 
DISK BLK 


MEMORY ALLOCATION SYNOPSIS: 


SECTION LTE: LOENT PLE 
BLK... 2 (RW, 1, bCL,REL,CON) 220232: 002546 01382, 
120232. 002244 01168... MYFILE O01 MCR OLB 1 
122476 000064 00052. FMTDV 01 MCRJOLEB 1 
TORESLS (RW; 1,bCL, Res CON) 123000 000024 00020. 
Using information in the Task Builder map, you can determine the 


and byte offset for the beginning of the file you 
want to change. The disk-block-limits line lists block 2 as’ the 
block where the program code begins. The synopsis lists byte 
offset 120232 as the beginning of the file MYFILE. To address 
location 574 in the MACRO-11 listing in task image mode, specify 
the following command line: 


block number 


Z2 A LO2ZS Zea, CRET > 
ZAP responds by opening the location and displaying its contents: 


UOZ2 LZ10267 032767 
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9.2.2.1 Using the Task Image Addressing Mode - In task image 
mode, ZAP allows you to address locations in a task image file by 
using the addresses the MACRO-11 assembler displays in its 
listing and the starting block number and byte offset listed in 
the Task Builder map. Unlike absolute mode, task image mode is 
useful for working with locations in an overlaid file because the 
Task Builder and ZAP perform the calculations necessary to relate 
the file’s disk structure to its run-time memory structure. 


9.2.2.2 Using the Absolute Addressing Mode - In absolute mode, 
ZAP processes the addresses you enter in the command lines as 
absolute byte addresses within the file. To use ZAP in absolute 
mode, invoke ZAP and enter the /AB switch with the file 
specification. 


ZAP interprets the first address in the file you are changing as 
virtual block 1, location 000000. All other addresses you enter 
are interpreted using this address as the base Locations 
Absolute mode allows you to access all the bytes in a data or 
task image file as well as the label and header blocks of a task 
image file on disk. However, to modify a disk task image, you 
must know the disk layout of the task image. Generally, absolute 
mode is practical only for data files or for task image files 
that are not overlaid. 


9.3 INVOKING AND TERMINATING ZAP 
To invoke ZAP type: 

S RUN $ZAP 
ZAP will prompt you: 

ZAP> 
You cannot enter a file specification on the same line that you 
use to invoke ZAP unless the file is an indirect command file. 
Refer to Section 9.3. When ZAP prompts you, enter the file 
specification for the file you want to change. You enter the 
file specification in the format: 


dev:[directory]filename.filetype;version[/sw...] 


The default file type is .TSK. After you enter the file 
specification, ZAP prompts with an underscore (_). 
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You terminate ZAP by entering the X command (explained in Section 
eo rene Ee This command exits you from ZAP and returns control to 
your 'DCh. 


9.3.1 Using Indirect Command Files with ZAP 


An indirect command file contains the specification for the file 
you want to work with and the appropriate ZAP commands. You can 
specify the indirect command file in the same command line in 
which you invoke ZAP. 


The following sample indirect command file (called CHANGE.CMD) 
contains ZAP commands. The commands will change the default 
priority of the despooler from 70 to 80 (120 octal). The V 
command (explained in Section 9.7.5) is used to verify that 70 
(106 octal) is what is actually in the location to be changed. 
The command file has the following ZAP commands: 


LPP.TSK/AB 
VE 3467 
106V 

120 

Xx 


To use the indirect command file type the following: 
7ZAP> G@CHANGE 


In this command, ZAP executes the commands in the file named 
CHANGE.CMD. 


The commands being used first open the task image file (LPP.TSK) 
in absolute mode (/AB). The next two commands open the desired 
location (byte 346 in block 0) and verify its contents (106). 
The next command changes the contents to 120, which will be the 
new default priority for the despooler. The X command exits you 
from ZAP and returns control to DCL. 


9.4 THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS 


ZAP commands perform functions that allow you to examine and 
modify the contents of locations in a file. Command lines 
comprise combinations of the following elements: 
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@ Commands 

© Internal registers 

@ Arithmetic operators 

@ Command line element separators 

@ The current location symbol 

@ Location-specifier formats 
The command elements can be combined to perform multiple 
functions. The function of a given command line depends not only 
on which elements you use, but also on the position of one 
element in relation to the next. 
The following sections describe the ZAP command line elements. 


Sections 9.5 and 9.6 describe how to combine the command line 
elements to execute ZAP functions. 


9.4.1 ZAP Commands 

There are three types of ZAP commands: 
® Open/close location commands 
@ General purpose commands 
@ <RETURND>D key 


The following sections describe each type of command. 


9.4.1.1 Open/Close Location Commands - Open/close location 
commands are nonalphanumeric ASCII characters that direct ZAP to 
perform a sequence of functions. Open/close commands specify two 
general sequences of operations: 


® Open a location, display its contents, and store the contents 
in the Quantity Register (see Section 9.6.2). 


® Close the location after (optionally) modifying it and open 
another location as specified by the command. 


Section 9.6 describes the format for specifying open/close 
location commands. 


THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS 


9.4.1.2 General Purpose Commands - ZAP provides Six 
Single-character, general purpose commands. You use these 
commands for calculating displacements, verifying location 
contents, and exiting from ZAP. You can enter some of the 
commands on the command line with no other parameters. Section 
9.7 describes the format for specifying these commands. 


9.4.1.3 <RETURN> Key - Unless there is another value or command 
on the line, the <RETURN> key closes the current location as 
modified and opens the next sequential location. ZAP commands 
take effect only after you press the <RETURN> key. 


9.4.2 ZAP Internal Registers 


ZAP internal registers are fixed storage locations that ZAP uses 
as registers. These registers contain values set by both you and 
ZAP. ZAP provides the following internal registers: 


@® Relocation Registers 0 through 7 (OR through 7R). These 
registers provide a means for indexing into a program section 
to change the contents of locations in the program section. 
You load the registers with the base address of the program 
section that has been relocated by the Task Builder. 


@ The Constant Register (C). You set this register to contain 
a 16-bit value, which you can specify as an expression in the 
ZAP command line. 


6 The Format Register (F). This register controls the format 
of the displayed address. If the value of the F Register is 
QO (the initial value), ZAP displays addresses relative to the 


largest value of any Relocation Register whose value is less 
than or equal to the address to be displayed. If the value 
of the Format Register is not 0, ZAP displays addresses in 
absolute byte format. 


@® The Quantity Register (Q). ZAP sets the value in the 
register to be the last value displayed at your terminal. 
To access the contents of a register, specify a dollar sign (S$) 
preceding the register name (in this case, C) in the command 
line. For example: 
_SC/<RET> 
C7 000000 
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This command line directs ZAP to display the contents of the 


Constant Register. The slash (/) is an open command described in 
Table 9-3. 


9.4.3 ZAP Arithmetic Operators 


Operators are single-character command line elements that define 
an arithmetic operation. Generally, ZAP evaluates these 
expressions as addresses. Table 9-1 describes the operators. 


You use the operators in expressions in command lines. For 
example, rather than manually adding all the displacements listed 
in the Task Builder map, you can specify a location using the 
EOu Lowing. notation: 


a2: 12000041 70/7<RET> 


This method for calculating such a displacement is faster and 
more accurate than doing it manually. 


Table 9-1: ZAP Arithmetic Operators 


Operator Function 


+ The plus sign adds a value to another value. Use 
it in an expression that ZAP then evaluates to be 
a command line element. 


~ The minus sign subtracts a value from another 
value. Use it an expression that ZAP then 
evaluates to be a command line element. 


* The asterisk multiplies a value by 50 (octal) and 
adds it to another value. Use it to forma 
Radix-50 string. 


The following example shows how to use the asterisk (*) to form 
Radix-50 strings. Section 9.5.4 explains the use of the colon 
and comma; the percent sign is an open command described in Table 
vate 
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_0,40/<RET> 
002:0,000040/ Q00001 
Le S34 RETS 

_/<RET> 

00220,0000407 000103 
_%<RET> 

002:0,000040% AS 


In this example, the first command opens the locations that is 40 
bytes offset from the location address contained in Relocation 
Register 0 and displays in octal format the contents of the new 
location. The location contains the value 000001. The second 
command converts 000001 to Radix-50 and adds 33 to the Radix-50 
value. The slash (/) command again displays in octal the value 
contained in the offset location. The value is now 103. The 
percent sign (%) command displays 103 in Radix-50 format. 


9.4.4 ZAP Command Line Element Separators 


ZAP provides separators to delimit one command line element from 
another. Different separators are required depending on the type 
of ZAP command being executed. See Table 9-2. 


Table 9-2: ZAP Command Line Element Separators 


Separator Function 


; The comma Separates a Relocation Register 
Specification from another command line element. 


; The semicolon separates an address from an 
internal register specification. Used in 
expressions that set values for Relocation 


Registers. 
The colon separates a block number base value from 


a byte offset into the block. Used in most of the 
references to locations ina file. 


9.4.5 ZAP Command Line Location-Specifier Formats 


ZAP has four formats for specifying locations in a command line. 


ga12 


THE ZAP COMMAND LINE AND COMMAND LINE ELEMENTS 


Fach provides a means of indexing into a file. 
The formats are: 

® Current location symbol 

@ Byte offset 

@® Block number:byte offset 


@ Relocation register, byte offset 


9.4.5.1 The Current Location Symbol - In command line 
expressions that ZAP evaluates as addresses, a period (.) 
represents the last open location. 


9.4.5.2 Byte Offset Format - You specify the byte offset format 
as follows: 


location 


If you are using ZAP in absolute mode, ZAP interprets this 
Specification as a byte offset from block 1, location 000000. 
This format is generally useful only when you are using absolute 
mode. 


The following ZAP command line opens absolute location 664 and 
displays its contents in octal format: 


_664/<RET> 


9.4.5.3 Block Number: Byte Offset Format - This format allows 
you to specify a byte offset from a specific block in the file. 
Specify the format as follows: 


blocknum:byteoffset 


You can use this format for addressing locations whether or not 
you enter the /AB switch with the file specification. 


In task image mode, ZAP allows you to enter the block number’ and 
byte offset displayed in the Task Builder map. The map gives 
information on the overlay segments ina task image file. Refer 
to Section 9.3 for more information. 
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9.4.5.4 Relocation Register, Byte Offset Format - This format 
allows you to load a Relocation Register with the address of a 
location. The address is then used as a_ relocation bias. You 
specify this format for addressing locations in a task image file 
as follows: 


relocreg,byteoffset 


Specify relocreg in the form nR, where n is the number of the 
Relocation Register. You can then address byte offsets from the 
address loaded in the Relocation Register. For example: 


_2:001254;3R<RET> 
_3,64/<RET> 
002:3,000064/ 037334 


The first command loads the address 001254 into Relocation 
Register 3, then the second command opens the location that is 64 


bytes offset from block 2, location 001254. The contents of that 
location are 037334. 


9.5 USING ZAP OPEN AND CLOSE COMMANDS 
This section gives examples of how to use the ZAP open and close 
commands. These commands allow you to open locations ina file, 


modify those locations, and close the locations. 


Table 9-3 summarizes the open and close commands 


Table 9-3: ZAP Open and Close Commands 


Command Name Description 
/ Slash Opens a location, displays its 
contents in octal, and stores 


the contents of the location in 
the Quantity Register (Q). If 
the location iS odd, <1t is 
opened as a byte. 


. Quotation mark Opens a location, displays the 
contents of the location as two 
ASCII characters, and stores the 
contents of the location in the 
Quantity Register (Q). 


g=14 


Command 


9 
i) 
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Name 


Percent sign 


Backslash 


Apostrophe 


RETURN key 


Circumflex or 
Up-arrow 


Underscore or 
Back-arrow 


At sign 


Description 


Opens a location, displays the 
contents of the location in 
Radix-50 format, and stores the 
contents of the location in the 
Quantity Register (Q). 


Opens a location as ae byte, 
displays the contents of the 
location in octal, and stores 
the contents of the location in 
the Quantity Register (Q). 


Opens a location, displays the 
contents as one ASCII character, 
and stores the contents of the 
Locat on in the Quantity 
Register (Q). 


Closes the current location as 
modified and opens the next 
sequential location if no other 
values or commands are on the 
command line. ZAP commands take 
effect only after you press’ the 
RETURN key. 


Closes the currently open 
location as modified and opens 
the preceding location. 


Closes the currently open 
location as modified, uses the 
contents of the location as _ an 
offset Erom the current 
Location, and opens the new 
location. 


Closes the currently open 
location as modified, uses the 
contents of the location as an 
absolute address, and opens that 
Location. 
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Command Name Description 
> Right angle Closes the currently open 
bracket location as modified, interprets 


the low-order byte of the 
contents of the location as the 


relative branch offset, and 
opens the target location of the 
branch: 

< Left angle Closes the currently open 

bracket location as modified, returns to 

the location from which the last 
series of underscore (nip Pa 
Sign (@), and/or right angle 
bracket (>) commands began, and 
opens the next sequential 
location. 

9.5.1 Opening Locations in a File 

Use any of the ZAP open commands -- slash (/), quotation mark 

("), percent sign (%), backslash (\), or apostrophe ('’) -- to 


open a location ina file. The format ZAP uses to display the 
contents of the open location depends on which operator you uSe. 


Once you open a location ina given format, ZAP displays in that 
format any other locations you open. For example, if you enter 
the percent sign (%) command, the contents of the open tJlocation 
are displayed in Radix-50 format. If you continually press the 
<RETURN> key, consecutive locations are displayed in Radix-50 
format until you change the format by entering a different 
special-character open command. 


9.5.2 Changing the Contents of a Location 


When you open a location with a special-character open command, 
you can change the contents of that location by entering the new 
value and pressing the <RETURN> key. The following example is a 
sequence of commands and ZAP responses that show how to open a 
location, change the value of the location, and close the 
location. 
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_/<RET> 
002:120000/ 000000 
_44444<RET> 
./<RET> 
002:120000/ 44444 


The first command (/) displays in octal format the contents 
(000000) of the current location. The contents are changed by 
entering the value 44444 and then the location is closed as 
modified by pressing the <RETURN> key. The slash (/) and 


<RETURN>- key display.the new. contents of the tocation: (fast line 
of example). 


9.5.3 Closing Locations in a File 


ZAP uses the <RETURN> key and other special-character commands 


for closing a location ina file. The close commands perform 
three functions: 


@® Close the current location 


@ Direct ZAP to another location (such as the preceding 
location or a location referred to by the current location) 


@ Open the new location 


The following sections give examples of how each command works. 


9.5.3.1 Closing a Location and Opening the Preceding 

Location - Use the circumflex (~) or up-arrow (#) 
command (depending on the type of terminal you are using) to 
close the current location, to direct ZAP to the preceding 
location, and to open that location. The following sequence of 
ZAP commands and responses shows how this command works: 


2120100 /7<RET> 
002:120100/7 000000 
_<RET> 

GOZsT20L027 0O0OLEL 
_<RET> 

002:120104/ 000222 
_<RET> 

00221200067 --000333 
“ <RET> 


00221201047 000222 
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The <RETURN> key closes the first three open locations and _ then 
opens the next location. The circumflex command closes location 
120106 and directs ZAP to open the preceding location, 120104. 


9.5.3.2 Closing a Location and Opening an Offset Location - 
Use the underscore (_) or back-arrow (#) command to close the 
current location, to direct ZAP to use the contents of the 
current location as an offset from the current location, and to 
open the new location. The following sequence of ZAP commands 
and responses shows how this command works: 


_2:120100/<RET> 
002:120100/7 000000 
_<RET> 

OUZ2IT2Z0L027 211 at 
_<RET> 

Q0 221201047: 222222 
_<RET> 

00221201067 000022 
__<RET> 
002232201327 123456 


The <RETURN> key closes the first three open locations. The 
underscore command closes location 120106, directs ZAP to use the 
contents (22) of the current location as the offset from. the 
current location (120110), and then opens that offset location 
(2013235 


9.5.3.3 Closing a Location and Opening an Absolute Location - 
Use the at sign (@) command to close the current location, to 
direct ZAP to use the contents of the just-closed location as the 
absolute address of a location, and to open that location. 


The following sequence of ZAP commands and responses shows how 
this command works: 


~221201007<RET> 
002:120100/ 000000 
_<RET> 

OOZeLZOLOZ7 Pia 
_<RET> 

OO2Z 2120104 120114 
_@<RET> 

QOZ2 T2011 47 11741 1.4 


The <RETURN> key closes the first three open locations. The at 
Sign command closes 120104, directs ZAP to use the contents 
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(120114) of that location as the absolute address of the next 
location to open, and then opens that location. 


9.5.3.4 Closing a. Location and Opening a Branch Target 

Location - Use the right angle bracket (>) command to 
close the current location, to direct ZAP to use the low-order 
byte of the contents of the just-closed location as a branch 
offset for the address of the next location, and then to open 
that. location, The following sequence of ZAP commands and 
responses shows how this command works: 


22120 L0G7<RET> 
002:120100/7 005000 
_<RET> 

OU Z2I20102Z/ 005361 
_<RET> 

002:120104/ 001020 
_><RET> 

OGZ31 201467 OS2712 


The <RETURN> key closes the first three open locations. The 
right angle bracket command closes location 120104, directs ZAP 
to use the low-order byte (020) of its contents as the branch 
offset for the address of the next location (120146), and then 
opens that location. 


9.5.3.5 Closing a Location and Opening a Previous Location - Use 
the left angle bracket (<) command to close the current location; 
to direct ZAP to the location where the current series of 
underscore (_), at sign (@), and/or right angle bracket (>) 
‘HEADER’ began; and then to open that location. The following 
sequence of ZAP commands and responses shows how this command 
works: 


_1202;0R<RET> 
_0,10/<RET> 

00220, 0000107 005212 
__<RET> 
002<0;,0052247- 001020 
_><RET> 
002:0,005266/7 000000 
_@<RET> 
002:0,000000/7 000000 
_<<RET> 
002:0,000012/ 000430 


The underscore command directs ZAP to location 005224. The right 


G2? 


USING ZAP OPEN AND CLOSE COMMANDS » 


angle bracket command directs ZAP to location 005266, and the at 
Sign command directs ZAP to location 000000. The left angle 
bracket command then directs ZAP to location 000012, which is the 
next sequential address after the location where the sequence of 
commands began. 


9.6 USING ZAP GENERAL PURPOSE COMMANDS 
This section explains the functions of ZAP general purpose 


commands and shows the formats for specifying them. Table 9-4 
describes the commands. 


Table 9-4: ZAP General Purpose Commands 


Command Function 
Xx Exits from ZAP; returns control to DCL. 
K Calculates the offset in bytes between an address 


and the value contained in a Relocation Register, 
displays the offset value, and stores it in the 
Quantity Register (Q). 


O Displays the jump and branch displacements from 
the current location to a target location. 


= Displays in octal the value of the expression to 
the left of the equal sign. 


V Verifies the contents of the current location. 


R Sets the value of -a. Relocation Register. 


9.6.1 The X Command 


Use the X command to exit from ZAP and then return control to 
Clas 


Specify the X command in the format: 


x 
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9.6.2 The K Command 


Use the K command to calculate the offset in bytes between an 
address and the value contained ina Relocation Register, to 
display the offset value, and to store it in the Quantity 
Register (Q). 


You can enter the K command in the following formats: 


K Calculates the offset in bytes between the address of 
the currently open location and the value of the 
Relocation Register whose contents are equal to or 
closest to (but less than) the value of that address. 


nK Calculates the offset in bytes between the currently 
open location and Relocation Register n. 


a;nkK Calculates the offset in bytes between address a and 
Relocation Register n. 


ZAP responds to the K command by displaying the Relocation 
Register it used and the offset value it calculated in the 
format: 


=reg,offset 
The following example shows how to use the K command: 


_eri i 250R<RET> 
woteeo ee ACRE LS 
Lt iZ0Zy/ CREP 
002:000020/ 000111 
_K<RET> 

=0 000010 
_0,100;1K<RET> 
=1,000040 


The first command sets the value of Relocation Register 0 to 
001172. The second command sets the value of Relocation Register 
1 to 001232. The slash command displays in octal format the 
contents of location 001202 (000111). The K command calculates 
the physical distance (offset) between the address of the 
currently open location (001202) and the value of the Relocation 


Register whose contents are equal to or closest to (but less 
than) the value of the address. ZAP then displays the number of 
the Relocation Register ist used (0) and the offset 


C00010=001202-001172).. 
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The last command adds 100 to the address in Relocation Register 0 
(001172) and then calculates the offset between the new address 0 
(001272) and the contents of Relocation Register 1 (001232). ZAP 
then displays the number of the specified Relocation Register (1) 
and the offset (000040=001272-001232). 


9.6.3 The O Command 

Use the O command to display the jump and branch displacements 
from the current location to a target location. A jump 
displacement is the offset between the open location and the 
target location. The jump displacement is used in the second 
word of a jump instruction if the instruction uses’ relative 
addressing. A branch displacement is the low-order byte of a 
branch instruction which, when executed, branches to the target 
Loeacvions 

You can enter the O command in the following formats: 


aQ Displays the jump and branch displacements from_ the 
current location to the target of the branch (a). 


aero Displays the jump and branch displacements from 
location a to target location r. 


The following example shows how to use the O command: 


The first number (000030) is the jump displacement; the second 
number (000014) is the branch displacement. 


9.6.4 The Equal Sign (=) Command 


Use the equal sign command (=) to display (in octal) the value of 
the expression to the left of the equal sign. 


Specify the equal sign command in the format: 
expression= 


The following example shows how to use the equal sign command 


G=22 
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(note that 177777 equals -1): 


gt 307 <RET> 
002:000030/ 000000 
_.+177756=<RET> 
000006 


The first command displays in octal format the contents of 
location 000030, which are 000000. The next command adds 177756 
to the address of the currently open location (000030). ZAP then 


displays the value of the specified expression (6=304+177756 or 
6=30-22). 


9.6.5 The V Command 


Use the V command to verify that a location contains a specified 
value. 


Specify the V command in the format: 
cOontcentsv 


You use the V command to ensure that, before you have ZAP change 
them, the contents being changed are what they should be. The V 
command is mainly useful in indirect command files because ZAP 
issues an error message and exits if the contents do not match. 
That way, the contents are not changed incorrectly. 


The following example shows how to use the V command; if you were 
using an indirect command file, you would include this sequence 
of ZAP commands in it. 


Oy 2007 
6V 
10 


ZAP opens the location that is 1200 offset from the value of 
Relocation Register 0 and ensures that the value contained at the 
location is 6. If so, ZAP changes the 6 to 10. If the value is 
not 6, ZAP exits. 


9.6.6 The R Command 


Use the R command to specify the value for a Relocation Register. 
AS -€xplained in Sections 9.3 and 9.5<2,; ZAP uses these registers 
to index into a program section so that you can change _ the 
contents of locations in the program section. 
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Specify the R command in the format: 
—contents;nR 


The variable nis the number of the Relocation Register (0 
through 7). 


For example: 


ahs CRE r> 

SIR AIT 
_125670;3R<RET> 
_$3R/<RET> 

S3R/ 125670 


The first command accesses the contents of Relocation Register 3, 
which ZAP displays in octal format as specified by the slash. 
The contents of the register are 177777. The next command 
changes the contents of the register to 125670. The last command 
again displays the contents of the register, which have been 
changed correctly. 


9.7 EXAMPLES 


This section gives examples of ZAP usage. The examples show the 
/LI switch segment table format and how you would use some of the 
ZAP commands. 


Some of the ZAP examples in this section are based on information 
contained in the following excerpts from a sample Task Builder 
memory allocation map and from the program code for some of the 
modules in the task. Each example follows the section of program 
code associated with it. 


Excerpts from Task Builder map: 


MAINMEO.TSK;1 Memory allocation map TKB M40.10 Page 1 
14-MAR-83 6 204 


Task name ) £66 MEO 

Partition name : GEN 

Identification : MOQ 

Task UIC S: 4-700;,200] 

Stack limits 000300: 0OL277 001000: 00512. 
PRG xfr address: 020520 

Task attributes: ID 

Total address windows: 2. 

Task image size : 9184. words, I-Space 


9-24 


Task Address limits: 


R-W disk blk limits: 


2520 < 


EXAMPLES 


words, 


MAINMEO.TSK;1 Overlay description: 


Base 


000000 
000000 


022140 
014124 


022140 
014124 


022320 
014170 


V22310 
014170 


Q223:10 
014170 


022310 
014170 


022140 
014124 


Top 
023135 
014173 


043645 
ees reo yg, 


022307 
014167 


022437 
014173 


022437 
014173 


022437 
ULaty 3 


022441 
014173 


O23 120 
014251 


MAINMEO.TSK;1 


MAINO 


KES ROOC SCOMeIL: 


R/W mem 


Disk blk limits: 


limits: 


Memory allocation synopsis: 


D=opace 
000000 043647 I-Space 
000000 015507 D-Space 
000002 000102 000101 00065, 


Length 

J2Z3136: 09822... MAINO 

014124 06228. D 

021506. 09030. -I INPUT 

001364 00756. D 

000150 00104. I CALC 

000044 00036. D 

000130 00088. I AADD 

000004 00004. D 

OU0T30° QOUSe. 1 SUBB 

000004 00004. D 

000130 00088. I MULL 

000004 00004. D 

000132 00090. I DIVV 

000004 00004. D 

001566 00886. I OUTPUT 

OVO1IZG: OU086.. BD 

Memory allocation map TKB M40.10 Page 2 

14-MAR-83 16201 
MAINO 
000000 023135 023136 09822. I-Space 
000000 014123 014124 06228. D-Space 
000002 000024 000023 00019. I-Space 
0:0;0:0:25° 000041. 0000TS: 00013:.. D=Space 
Title Ident 
000300 000216 00142. 


BLK.:(RW,1,LCL, REL, CON) 


9225 


Sob 0B. OLB Fi 


MAINMEO.TSK;1 


INPUT 14-MAR-83 202 Ud. 

eee SeGmMent:: INPUT 

R/W mem limits: 022140 043645 021506 09030. 
014124 015507 001364 00756. 

Disk blk limits: 000042 000063 000022 00018. 
000064 000065 000002 00002. 

xxk Segment: CALC 

R/W mem limits: 022140 022307 000150 00104. 
014124 014167 000044 00036. 

Disk blk limits: 000066 000066 000001 00001. 
000067 000067 000001 00001. 

xxx Segment: AADD 

R/W mem limits: 022310 022437 000130 00088. 
014170 014173 000004 00004. 

Disk blk limits: 000070 000070 000001 00001. 
000071 000071 000001 Q0001. 

xx*e Segment: SUBB 

R/W mem limits: 022310 022437 000130 00088. 
014170 014173 Q00004 Q0004. 

Disk Dik Limits: Q00072 0000/2 Q00001 OQ0001. 
000073 000073 000001 00001. 
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000300 000216 00142. 


Memory allocation map 


TKB M40.10 


L=Sspace 
D=opace 


I=-Space 
D-Space 


CBTA 


I=Space 
D=Space 


E=-Space 
D-Space 


L=ppace 
D=5 Dace 


L-opace 
DSpace 


l=Space 
D=opace 


l=Space 
DSpace 


04. 


Page 4 


Page 5 


Page / 


Page 8 


3 


k*k* seg 


R/W mem 


Disk bik Limits: 


MAINMEO.TSK;1 


DIVV 


ment: 


limits: 


xkxk Segment: 


R/W mem 


Disk blk limits: 


limits: 


Axe SeOGmMent.: 


R/W mem 


Disk blk limits: 


limits: 


022310 022437 000130 00088. 
014170 014173 000004 00004. 


000074 000074 000001 00001. 
000075: 000075. QO000T “Q0001. 


EXAMPLES 


14-MAR-83 


022310 
014170 


000076 
000077 


OULeEOT 


022140 
014124 


000100 
000102 


022441 
014173 


000076 
000077 


026725 
014251 


000101 
OOOLO2 


Memory allocation synopsis: 


Section 
File 


SYOLIB. 


SYoL1B . 


SYSLIB. 


Soto LIB. 


OLB? 7 
OLBS 
OLB? 7 


OLB. 7 


a*(RW,1,5CEh,REb; CON) 


16201 


000132 
000004 


000001 
000001 


001566 
000126 


000002 
000001 


022140 
022140 


022202 


O2Z2276 


022424 


00090. 
00004. 


00001. 
00001. 


00886. 
00086. 


0900 2% 
00001. 


000374 
000042 


000074 


000126 


000110 


Memory allocation map TKB M40.10 


Page 9 
I-Space 
D-Space 
L=SpDace 
D-Space 
Page 10 
l=space 
D=space 
I-Space 
D-Space 
Page 11 
I-Space 
D-Space 
l=opace 
D-opace 
Title Ident 
OU 252% 
00034. SAVAL 00 
00060. CATB 03 
00086. CDDMG 00 
O00 72 <CsTA 02 
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Example 1: 
In this example, the segment table for task MAINMEO is requested. 
Note that the segment table corresponds exactly to the overlay 


description list given in the Task Builder map. The sequence of 
ZAP commands is as follows: 


NOTE 
This example was taken from a PDP-11 running 
RSX-11M-PLUS. The example serves to show users 
how to use ZAP. Note, however, that I and D 


Space capability is not currently supported. 


ZAP>MAINMEO/LI 

ZAP Version V02.01 COPYRIGHT 
CORPORATION 1983 

Segment Table 


(Cc) DIGITAL EQUIPMENT 


000002: 000000-022137 MAINO I-space root 
000025: 000000-014123 MAINO D-space root 
000042: 022140-043647 INPUT I- and 
000064: 014124-015507 INPUT D-space 
000066: 022140-022307 CALC I- and 
000067: 014124-014167 CALC D-space 
000070: 022310-022347 AADD I- and 
000071: 014170-014173 AADD D-space 
000072: 022310-022437 SUBB I- and 
000073: 014170-014173 SUBB D-space 
000074: 022310-022437 MULL I- and 
000075: 014170-014173 MULL D-space 
000076: 022310-022443 DIVV I- and 
000077: 014170-014173 DIVV D-space 
0001002 U22140=023727 “OUTPUT I- and 
O00102: 014124-014253: OUTPUT D-space 


in Example 1, 
command 


line 


the first command line invokes ZAP and 
segment table for the task MAINMEO. 


requests 


the 


the second 


The /List switch directs ZAP to give the starting disk block for 
root segment of the task (in this example, MAINO) and for 
each segment overlaid on the root of the task. The /List switch 


lists 


the base 


and 


top addresses, 


plus the segment text 


string for each segment. 


Because this is an I- and D-space overlaid task, there is an 
I-space root segment and a D-Sspace root segment and each is a 
part of the root segment of the task MAINO. In this example, the 
I-space root segment begins at disk block 2. The addresses for 
the I-space root segment range from 000000 to 022137. The next 
line of numbers is for the D-space root segment which begins at 
disk block 25. The addresses for the D-space root segment range 


2220 
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From 000000 to 014123. The next line of numbers is for the 
segment INPUT. That I-space segment begins at disk block 42 and 
the D-space segment begins at disk block 64. The I-space 
addresses range from 022140 to 043647 and the D-space addresses 
range from 014124 to 015507. The table continues’ for the 
remaining overlaid segments in the task MAINMEO. 


Example 2: 
In this example, the contents of a location in another’ task 
module (TEST.MAC) are being changed. The following excerpt from 


the module shows the associated code. 


TEST - TEST MACRO FILE MACRO M1113 18-MAR-81 07:48 PAGE 8-1 


1269 ; THIS IS A PART OF THE MODULE 
1270 : TEST.MAC 

12d ; WHICH IS IN THE ROOT SEGMENT: 
i272 : TEST 

L273 : 

1274 010132 010146 MOV R1,-(SP) 
1275 010134 012704 041114 MOV #"LB,R4 
1276 010140 005003 CLR R3 

IZ]. 010142 CALL SFNDUB 
1278 010146 010146 MOV R1,-(SP) 
1279 010150 012704 050123 MOV #"SP,R4 


The sequence of ZAP commands is: 


wAZ2siZzi244s0RCRET> 
Oot O0L26 <RET> 
042:131402" LB 


= <RET> 
042:131402’ L 
a2) REL > 
042:131403’ B 
S204 RET 


020136 <REP> 
042:131402" LP 


The first command line loads the starting address of TEST.MAC 
(121244 in disk block 42) into Relocation Register 0. The second 
command line displays as an ASCII word the contents of location 
10136 of the module. The contents are LB. The first apostrophe 
command (’) displays the first byte of the word (L) and _ the 
second command displays the second byte (B). The following 
command line changes the contents of the second byte to 120, 
which is the ASCII code for the letter P. The last command 
displays the new contents of location 10136, which are now LP. 


EXAMPLES 


Example 3: 


In this example, the contents of a location are also being 
changed. This time, the location is in the module TSTVB1.MAC. 
The following excerpt is the associated code. 

TSTVB1 - TSTVB1 MACRO FILE MACRO M1113 18-MAR-81 07:52 PAGE 4-2 
155 ; PART OF MODULE TSTVB1.MAC 
154 ; WHICH IS ALSO IN THE ROOT SEGMENT: 
155 : | TES? 

L356 ; 

157 000334 Q05702 | Loe R2 

158 000336 001404 BEQ pases: 

159. -000340 ‘052767 000060 172516 BIS #60,SR3 

160 000346 000403 BR ios 

The sequence of ZAP commands is: 


JeZe Ls oe 7ST RCRETS 
oy 3427 CRET> 
04221340327 000060 
_100<RET> 
_1,342/<RET> 
042:134032/ 000100 


TSTVB1L.MAC 
The second 
S42 sn 


The first command line loads the starting address of 
(133470 in disk block 42) into Relocation Register 1. 
command line displays in octal the contents of location 


the module. The third command line changes the contents of this 
location from 60 to 100. The last command line displays the new 
contents (again in octal). 

Example 4:3 

In this example, the operation code (op code) for one of the 


instructions in another module is being changed. The module is. 


TSTCM.MAC, and the following excerpt is the associated code. 

TSTCM - TSTCM MACRO FILE MACRO M1113 18-MAR-81 07:47 PAGE 3-7 
AQ2 > PART OF THE-MODULE TSTCM.MAC 

403 ; WHICH IS IN THE: SEGMENT: “TSTCM 

404 : 

405: OOL2Z72. OF3127 LIT 766 ASHC Hoe Os Ra 

406 001276 010037 00000G MOV RQ, @#KISAR6 

407 001302 062701 140002 ADD #1400004+2,R1 

The sequence of ZAP commands is: 


EXAMPLES 


_113:154530;R2<RET> 
2,1302/<RET> 

TL StLooUSsZy Vole 01 

_162701<RET> 

_2,1302/<RET> 

LIBS 560327 162701 
Xx 


The first command line loads the starting address of TSTCM.MAC 
(154530 in disk block 113) into Relocation Register 2. The 
second command line displays in octal the current instruction 
contained in location 1302. The instruction includes the op code 
06 for the ADD operation. The third command line changes the op: 
code to 16, which signifies the SUBTRACT operation. The fourth 
command line displays the new contents of the location and the X 
command ends the ZAP session. 


9.8 ZAP ERROR MESSAGES 

This section lists the messages generated by ZAP, explains’ the 
condition that causes each message, and suggests a response to 
the message. 


ZAP -- ADDRESS NOT WITHIN SEGMENT 


Explanation: The address specified was not within the 
overlay segment specified. 


User Action: Reenter the command line, specifying the 
correct address or overlay segment number. 

ZAP -- CANNOT BE USED IN BYTE MODE 
Explanation: The at sign (@), underscore (_), and right 
angle bracket (>) commands cannot be used when a location is 


opened as a byte. 


User Action: If the location is an even address, open the 
location as a word. 
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ZAP -- ERROR IN FILE SPECIFICATION 


Explanation: The file Specification was entered 
incorrectly: 


User Actions Reenter the command line, using the correct 
file specification. 


ZAP -- ERROR ON COMMAND INPUT 


Explanations An I/O error occurred while a command line was 
being read. This could be a hardware error. 


User Actions Ensure that the hardware is CUNCTCLIONINng 


properly. If it is, reenter the command line. If not, call 
your DIGITAL Customer Support: Center. 


ZAP -- I/O ERROR ON TASK IMAGE FILE 
Explanation: An I/O error occurred while the file being 
modified was being read or written. This could bea 
hardware error. 
User Action: Ensure that the hardware is Pune tLOnang 
properly. If it is, reenter the command line. If not, call 
your DIGITAL Customer Support Center. 

ZAP -- NO OPEN LOCATION 


Explanations: You attempted to modify the contents of a 
closed location. 


User Actions Open the location to perform the modification. 
ZAP -- NO SUCH INTERNAL REGISTER 


Explanations The character following a dollar sign was not 
a valid specification for the internal register. 


User Actions: Reenter the command line, specifying the 
correct value. 
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ZAP -- NO SUCH RELOCATION REGISTER 


Explanations: An invalid number’ was specified Lor a 
Relocation Register. 


User Actions: Relocation Registers are numbered 0 through 7. 
Any other numbers are illegal. Reenter the command line, 
specifying a valid Relocation Register number. 


ZAP -- NO SUCH SEGMENT 


Explanations The starting disk block was not the start of 
any segment in the task image file on disk. 


User Actions Reenter the command line, specifying the 
correct disk block address. 


ZAP-- NOT A TASK IMAGE OR NO TASK HEADER 


Explanations: An error occurred while the segment tables 
were being constructed. Possibly, the file is not a task 
image, the /AB switch was not specified, or the task image 
is defective. 


User Action: Terminate the ZAP session, then try invoking 
ZAP with the /AB switch specified. 


ZAP -- NOT IMPLEMENTED 


Explanation: You entered a command that is recognized by 
ZAP, but not implemented. 


User Action: Ensure that you entered the command correctly. 


ZAP -- OPEN FAILURE FOR TASK IMAGE FILE 


Explanation: The file to be modified could not be opened. 
Possibly, the file does not exist, the file is locked, the 
device is not mounted, or you do not have write-access_ to 
the file. 


User Action: Check the file specification for errors, or 
check your file access privileges. Refer to Section 3.21 
for an explanation of the DIRECTORY command and the /FULL 
qualifier. 
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ZAP -- SEGMENT TABLE OVERFLOW 


Explanation: ZAP does not have enough room in its partition 
to construct a segment table. 


User Actions You cannot use ZAP on the file. 


ZAP -- TOO MANY ARGUMENTS 


Explanations You entered more arguments on the command line 
than are allowed. 


User Actions Reenter the command line, specifying the 
COPrecL”: Syntax. 


ZAP -~- UNRECOGNIZED COMMAND 
Explanations ZAP did not recognize the command as entered. 


User Action: Check the syntax of the command you are trying 
to execute, then reenter the command line, specifying the 
COrPTrece Syntax. 


ZAP -- VERIFY FAILURE 


Explanations The V command determined that the contents of 
a location did not match the expected value. ZAP 
terminates. 


User Action: If applicable, check for errors in the 
indirect command file. Ensure that the contents of the file 
are what they should be. Locate the cause of the error and 
reenter the command line. Ensure that you are correcting 
the right file or file version. 


CHAPTER 10 
SOURCE LANGUAGE INPUT PROGRAM (SLP) 


The Source Language Input Program (SLP) is a utility used to 
maintain and audit source files. The optional audit trail in the 
output files allows you to keep a record of maintenance changes. 


SLP is invoked by edit command statements and switches. SLP edit 
command statements allow you to: 


@ Update (delete, replace, add) lines in an existing file 
@ Create source files 


® Run indirect files containing SLP edit commands 


Input to SLP is a file that you want updated and command input 
consisting of text lines and edit command lines that specify the 
update operations to be performed. To locate lines to _ be 
changed, SLP uses line numbers or character strings that you 
specify. Command input can come directly from your terminal or 
from an indirect command file containing commands and text lines 
to be inserted into the file. SLP accepts data from any FILES-11 
volume. 


Output from SLP is a listing file and the updated input file. 
SLP provides an optional audit trail that helps you keep track of 
the update status of each line in the file. If an audit trail is 
not suppressed, it is shown in the listing file and permanently 
applied to the output file. 


You can control SLP processing with SLP control switches. These 
Switches allow you to: 


@® Suppress audit trails 


@ Specify the length and beginning position of the audit trails 
@ Calculate the checksum value for the edit commands 


@ Generate a double-spaced listing 


To invoke SLP type: 


BPE /She (Peter £6: EDIT /SEP In Chapter 3) 


S RUN SSLP 
SLP will prompt: 
SLP> 


You should not specify TI: as your output file, because when you 
finish editing, you will not have a copy of the output file and 
the input file will be the same as before you began editing. 


10.1 SLP INPUT AND OUTPUT FILES 


SLP requires two types of input, an input file and command input. 
The input file is the source file you want to update using SLP. 
Command input consists of SLP edit commands and, optionally, new 
lines of text to be placed in the file. 


SLP output consists of an output file and a listing file. The 
output file is the updated input file. The listing file is a 
copy of the output file with line numbers added. Both show the 
changes SLP made to the file. 


10.1.1. The Input File 


The input. file is. the tile to be updated by ShPs. IU can -contain 
as. many (lines. -Of ‘text as: are required. When SEP. processes: the 
input file, it makes the changes specified by SLP edit commands. 
If an audit trail is generated, these changes are noted in the 
output files. 
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10.1.2 Command Input 


SLP uses command input to update files. Command input can _ be 
entered interactively after you invoke the SLP utility or 
indirectly by means of indirect command files. 


You enter command input to SLP in two modes: command mode and 
edit mode. After it is invoked, SLP iS in command mode, where 
the first line entered must be the command line defining the 
files to be processed. When SLP accepts this line, it 
initializes the files you want processed. Once these files are 
initialized, SLP enters edit mode, where it interprets the lines 
you enter as SLP edit commands or new input lines. 


You terminate command input with a single slash as the first 
character of an edit command line. 


The following example shows the general form of command input: 


MYPILE MAC +2 /CS7AU?559210,MYP LGR. LST ISMYFILE MACs i 


Say pO Ze 

CMP (R1)+,B 

-~4,4 

DEG. RZ 

A 

NOTE 

Numeric values given for switches default to 
octal. Decimal values must be followed by a 
period (.). The default position for the audit 
trail is 80 (decimal) and its default length is 8 
(decimal); no more than 14 (decimal) characters 
may be specified. (See Section 10.4.2 for more 


information about the audit trail.) 


The first line is the command line, where you define the output 
file,..' the 1asting file, and the input file. The mext: four -idanes 
comprise the SLP edit commands and input lines. 


Note that the input and output files in the example have the same 
file name and file type; only the versions are different. To 
ensure that the correct files are processed, specify the version 
numbers explicitly when you enter the SLP command line. 
Wildcards cannot be used in any of the file specifications. 


You can also calculate the checksum value for the edit commands. 


Specify the checksum switch with either the input or output file 
specification in the format: 


L0=3 


SLP INPUT AND OUTPUT FILES 


ar e 7 
pCO | 


The checksum value can be calculated for all  SLP edit command 
lines. The checksum value cannot be calculated for the 
following: 


e The command line specifying the input and output files. 
@® Comments in the edit command lines. 


® Any spaces and/or tabs between characters included in the 
checksum calculation and those characters excluded from the 
calculation. 


® The second comma and anything following it in an edit command 
line (that is, audit trail and/or comment). 


® Comment delimiter (specified by the first character of the 
last audit trail string before the current delimiter) and any 
characters following it in an input line, whether or not it 
is being used in the line as a delimiter. The value is then 
reported in a message on your terminal. If you specify a 
value for the checksum and it is not the same as the 
calculated checksum, you will get a diagnostic error message. 
(The messages are described in Section 10.5.2.) 


10.1.3 The SLP Listing File 


The SLP listing file shows the updates made to the source file. 
Each line in the listing file is numbered. Updates are marked by 
means of the audit trail if one has been generated. The examples 
given throughout this chapter contain samples of listing files. 


10.1.4 The SLP Output File 


The SLP output file is the updated input file. All of the 
updates specified by command input are inserted in this file. 
The audit trail, if specified, is applied to lines changed by the 
update. The audit trail is included in the output file. The 
numbers generated by SLP for the listing file do not appear in 
the output file. 
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10.2 HOW SLP PROCESSES FILES 


This section describes how SLP porcesses files when it receives 
the following command line and edit commands. 


MYFILE.MAC;2/AU:55:10,MYFILE.LST/-SP=MYFILE.MAC:1 


ae ae 


~3 

CMP (R1)+,B 
-~4,4 

DEC (R2) 

ie 


This is the input file (MYFILE.MAC;1) before SLP processes’ the 
files: 


MOV #BUF1,RO 
MOV #STZ,R1 

CALL READ 

TST R2 

BEQ END 

CLR R1 

MOV R2,NUMC 

CMPB (RO)+,A 

BNE 20$ 

INC R1 


The following is the listing file (MYFILE.LST;1) resulting from 
SLP processing of these files: 


1. MOV #BUF1,RO 

oe MOV #SIZ,R1 

om CALL READ 

4. CMP (R1)+,B ; **NEW* * 

oa DEC (R2) ; *XNEW** 

6. BEQ END exkek 71 

dx CLR Rd 

Sa MOV R2,NUMC 

9. CMPB (RO)+,A 

10. BNE 209 

it. INC Ri 
The audit trail shows the new lines (;**NEW**) and indicates 
where lines have been removed (;%**-1). (The audit trails 


;**NEW** and ;**-n are automatically generated by SLP if you have 
not suppressed audit trail generation or if you have not 
specified another audit trail string.) In this case, a line has 
been added after line 3, and line 4 has been deleted and a new 
line added in its place. 
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SLP processes an input file using command input. When processing 


begins, SLP writes each line from the input file into the output 
file until it reaches a line to be modified, as requested in the 
command input. When SLP reaches a line to be modified, it 


modifies the line, notes the change by means of the audit trail, 
and then continues writing lines to the output file until another 
command is encountered or until end-of-file is reached. 


10.3 USING SLP 
This section describes how to: 

@ Specify the SLP edit commands. 

© Update files using the SLP edit commands. 


e Enter SLP commands interactively and by means of indirect 
command files. 


@e Create a source file using SLP. 


10.3.1 Specifying SLP Edit Commands 


The SLP edit commands allow you to update source files by adding, 


deleting, and replacing lines ina file. SLP allows you to enter 
lines sequentially. Once past a given line in the file, you 
cannot return the line pointer to that line. To return the line 


pointer to that line, you must begin another SLP editing session. 
You enter SLP edit commands after invoking SLP and specifying an 
edit command line. 


The general format of the SLP edit command line is as follows: 


“| LOCatOr.. | {| ,LoCaton2 || s7audittranly | (7 comment) 
inpuclLine 


- (dash) 
Identifies a SLP edit command line. 
locatorl1 


A line locator that causes SLP to move the current =ILline 
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pointer to a specified line. If you specify only locatori, 
the current line pointer is moved to that line and SLP reads 
the next line in the command input file. This field can be 
specified using any of the locator forms described later in 
this section. 


locator2 
A line locator that defines a range of lines (that is, the 
range beginning with locatoril and ending with locator2, 
inclusive) to be deleted or replaced. This field can _ be 


specified using any of the locator forms described later in 
this section. 


faudittrail/ 
A character string used to keep track of the update status 
of each line in the file. The string must be enclosed 
within slashes (/). It consists of a comment delimiter as 


the first character and then a text string. The semicolon 
(;) is the default delimiter for audit trails automatically 
generated by SLP (;**NEW** and ;**-n). The comment 
delimiter specified in audittrail (usually a semicolon) is 
the new delimiter for all subsequent audit trails until 
redefined by a later audittrail. 


inputline 
A line of new text to be inserted into the file immediately 
following the current line. You can enter as many input 
lines as required. 

comment 
A line of text (delimited by a semicolon) at the end of the 
SLP edit command line that appears only in the command input 


file. 


All fields in the SLP edit command line are positional and commas 
must be specified. 


The locator fields can take one of the following forms: 


-/string/[+n] 
a/ SUV ING s-1e5CPAng7 +n 
-~number[+n] 


string 


A string of ASCII characters. SLP locates the line where 
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the string exists and moves the current line pointer to that 


line. If the locator 1s specified im the form 
/string...string/, SLP locates the line where the two 
Character strings delimit a larger character string 


abbreviated by an ellipsis (...). 
number 


A decimal line number where the current line pointer is to 
be moved. The largest line number that can be specified is 
9999. 


- (period) 


The current line. 


A decimal value used as an offset from the line specified by 
the locator. You cannot use +n by itself. It must be 
specified with a number or string locator or a period. SLP 
moves the current line pointer n lines beyond the line 
specified in the locator field. 


Although the values for number and n are taken as decimal, 
remember that all other SLP values are octal by default. 


All forms of the line locator can be specified interchangeably in 
the SLP edit command lines. 


10.3.2 Entering SLP Edit Commands 


Once you have invoked SLP, you can enter SLP edit commands 
interactively or by specifying indirect command files. In both 
cases, the first command you must enter is the command line 
defining the files to be processed during this SLP session. This 
section gives examples of how to use both methods of entering SLP 
commands. 


The following file (BASE.MAC;1) is used as the input file for the 
examples in this section: 


MOV #tSSWTCH,R3 

CLR SERFLG 

CLR SCRCVL 

CLR SCSSV 

MOV SPSAV,SP 

MOV #tSCFNMB, RO 

MOV # <SHDSIZ-SCFNMB>/2+1,R1 
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CLR (RO)+ 
DEC R1 
BNE 59 


10.3.2.1 Entering SLP Commands Interactively - To alter the 
example file interactively, invoke SLP. Once you have entered 
the SLP command mode, SLP does not display prompts. The first 
line you enter must always be the command line defining the files 
you want processed during this session: 


a 


In this example, the edit commands instruct SLP to do_ the 
following: -3 inserts a new line after line 3; -4,4 deletes line 
4 and replaces it with a new line; -6,,/;JM010/ inserts a line 
after line 6 with a new audit trail value. 


When you have entered all the corrections, enter the slash (/) to 
terminate the edit session. SLP processes the files and returns 
control to you with the prompt: 

siLP> 


This returns SLP to command mode. You can then enter another 
input file and begin another editing session. 


The listing file (BASE.LST;1) resulting from SLP processing 
appears as follows: 


1. MOV #SSWTCH,R3 

2. CLR SERFLG 

Sy. “COR SCRCVL 

4. TST R1 -kkNEW** 
5. BEQ 10S > kkKNEW* * 
6. MOV SPSAV,SP sk*k-1 

7. MOV +SCFNMB,RO 

8? CLR R2 > JM010 
9. MOV # <SHDSIZ-SCFNMB>/24+1,Ri 
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10% “CGR (RO)+ 
142. DEC R1 
12. BNE 58 


The /TR switch (/TR in the command line) records the truncation 
of lines by the audit trail. In the listing file, a question 
mark (?) replaces the period (.) after the line number for’ the 
lines that were truncated. It 1S possible that audit-trail 
strings in the input file will be truncated by the new 
audit-trail string, although the commands or text strings will 
not be truncated. 


10.3.2.2 Entering SLP Commands Using Indirect Command Files 

- To alter the example file by using the SLP edit commands in 
the indirect command file, BASE.SLP, you invoke SLP and SLP 
responds with the prompt: 


SLP> 
You then enter the file specification for the indirect command 
file containing the command line, the SLP edit commands, and the 
input lines: 


@BASE.SLP 


SLP processes the files just as if you entered the commands and 


input lines interactively, returning control to you with the 
prompt; 

SLP> 
The output listing resulting from indirect command file 


processing is exactly like the output listing resulting from the 
Same changes made interactively. 


Indirect command files can be nested to a maximum level of three. 
This permits indirect command files to reference a text file. 


10.3.2.3 Using SLP Operators - In addition, you can enter 
special characters called operators, which perform specific 
Functions. Table 10-1 lists the operators and the function each 
performs. Enter Operators, in. edit mode, as the first character 
Of “al 1mput lane. 
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Table 10-1: SLP Operators 


Operator Function 


- Identifies the first character of a SLP edit 
command line. 


\ Suppresses audit-trail processing. 

% Reenables audit-trail processing. 

@ Invokes” an indirect command file for SLP 
processing. 

ff Terminates the SLP edit session, and then returns 


to SLP command mode. 


< Enables you to enter characters in the input file 
that SLP otherwise would interpret as operators. 
For example, </ hides the slash character from 
SLP, thereby enabling you to enter the slash into 
the output file without terminating the SLP 
editing session. This character can be used with 
all SLP operators. 


10.3.3 Updating Source Files With SLP 


This section describes the procedure for generating a numbered 
listing for use in editing source files by line number. The 
section also describes how to use SLP to add, delete, and replace 
lines ina file. 


10.3.3.1 Generating a Numbered Listing - SLP processes input by 
line number. However, line numbers appear only in the listing 
file; they are not written to the output file. To use SLP 
effectively, you should use a numbered listing when you prepare 
command input. To generate a numbered listing, first invoke SLP, 
then enter the command line in the format: 


LUStftile=intile 


1 ee 


USING SLP 


In this format, listfile is the name you assign to the listing 
file SLP will produce and infile is the name of the input file 
whose lines are to be numbered. The slash (/) terminates edit 


mode. For example, suppose the input file is: 
MOV Ri ,=(SP)} 
BIC #177770; €4SP 
ADD #60,@SP 
MOVB (SP)+,-(RO) 
ASR Ri 
ASR R1 
ASR R1 
DEC R2 
BNE 305 
MOV #MSG,RQ 


SLP processes each line to generate a numbered list file (list 
files): 


Ie “MOV. Ri,-(SP) 

2. BIC #177770,@SP 
3. BADD #60,@SP 

4. MOVB (SP)+,-(RO) 
5. ASR R1 

6. ASR R1 

7. ASR R1 

8. DEC R2 

9. BNE 30S 
10. MOV #MSG,RO 


10.3.3.2 Adding Lines to a File - The three SLP edit command 
formats for adding lines to a file are: 


or 
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LOcCatLorl,,favdittrari7 
inputline 


The following example shows how to add lines to a 
command input consists of the following lines: 


file. The 


MYFILE.MAC;2/AU:48.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;1 
~3 
CMP 
-4,4 
DEC R2 
-6,,,/;IMO01L0/ 
INC R3 
=9,,7 -BI0087 
BEQ 10S 

ye 


(R1)4+,B 


The next example uses text rather than line numbers’ to 
where new lines should be added or deleted: 


indicate 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 
~/BEQ/ 
CALL 

/ 


WRITE 


In this example, the edit command /BEQ/ instructs SLP to insert a 
line after the line with the first occurrence of BEQ. | 


SLP processing generates the following Las tang file 
(MYPIGLE. bors.) 
1. MOV #BUF1,RO 
2. MOV #SIZ,R1 
3. CALL READ 
as. TS? R2 
Be BEO END 
6. CALL WRITE ; *XNEWX* * 
ie “CLR Ri 
8. MOV R2,NUMC 
9. CMPB (RO)+,A 
10. BNE 205 
ida NC R1 
SLP has numbered the lines and applied an audit trail to the line 
following dbine. “5, where ‘“SLP found the first occurrence of the 
string BEO. 
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The next example uses the same input file and the following new 
command lines: 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 
ASHRSTT LD 

CMP (Rij eB 

/ 

7. 


oLP processing generates.the following listing file (MYFILE;1): 


1. MOV #BUF1,RO 
2. MOV #SIZ, Rd 
32. "CAEL READ 

4. TST R2 

S. CMP (R1)+,B ; * KXNEW** 
6. BEQ END 

Tea ER R1 

8. MOV R2,NUMC 
9. CMPB (RO)+,A 
10. BNE 20S 
Lic - arNG R1 


Again, SLP has numbered the lines and this time the new input 
line is inserted so that it is two lines beyond the line 
containing the first occurrence of the string /#SIZ/. 


10.3.3.3 Deleting Lines from a File - The SLP edit command 
format for deleting lines from a file is: 


~(~locatorl]; locatorzZ |,[.f/audittraily )]) 13 comment | 

In this format, locatorl and locator2 can be any of the forms of 
the LreCator fields described in Section 10.3.1; =locatorl 
specifies the line where SLP is to begin deleting lines; locator2 
specifies the last line to be deleted. SLP deletes all lines 
from locatorl1 through locator2, inclusive. 


Suppose an input file consists of the following lines: 


MOV #BUF1, RO 
MOV #SIZ,R1 
CALL READ 

TST R2 

BEQ END 

CLR R1 

MOV R2,NUMC 
CMPB (RO)+,A 
BNE 205 

INC R1 
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To delete lines from the file, the command input can consist of 
the following commands and text lines: 


MYFILE.MAC:2/AU:50,MYFILE.LST=MYFILE.MAC;1 
-~/MOV...R1/,/NUMC/ 
a 


SLP processing generates the following listing file (MYFILE;1): 


1. MOV #BUF1,RO 

2. CMPB (RO)+,A 

3. BNE 205 

4. INC R1 7k k-6 
In this example, the ellipsis (...) abbreviates the larger string 
MOV #S1Z,R1. Assuming the two strings bracket a larger string, 


SLP searches for the first occurrence of the string MOV and then 
the first occurrence on the same line of the string R1, in this 
case the string MOV #SIZ,R1. SLP begins deleting lines at this 
line and continues deleting lines until it deletes the last line 
of the given range, specified here by the string NUMC. SOP 
applies the audit-trail count of the lines it deleted to the next 
line from the input file. 


Using the same input file as used in the previous example, the 
following example shows how to delete a single line using the 
period locator. The command input for this example is: 


MYFILE.MAC;2/AU:50,MYFILE.LST=MYFILE.MAC;1 
=f MOV #SIZy RLS ys 
a 


SLP processing generates the following listing file (MYFILE;1): 


1. MOV #BUF1,RO 

Da “CRETE READ kk 1 
3. TST R2 

4. BEQ END 

5. CLR R1 

6. MOV R2,NUMC 

7.  CMPB (RO)+,A 

8. BNE 20$ 

9. INC R1 


SLP moves the current line pointer to the line containing the 
string MOV #SIZ,R1 and then finds the period as the second 
locator field. Since the second locator field is specified as 
the current line, SLP deletes the current line. 
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10.3.3.4 Replacing Lines in a File - A replacement is the 
deletion of old text followed by the insertion of new text. The 
number of lines deleted need not match the number of lines added. 
To replace lines in a file, use the same SLP edit command format 
as used in the delete command. The first line locator field 
Specifies the first line to be deleted. The second line locator 
field defines the last line in the range to be deleted and where 
the new text is to be inserted. For example: 


Bbc 


This command instructs SLP to move the line pointer to line 4, 
and replace line 4 and the next four lines with new input lines. 


The following example shows how to delete lines from a file and 
replace them with new Ilines. The i1nput file consises. of the 
following lines: 


MOV #BUF1,RO 
MOV #SIZ,R1 

CALL READ 

LoL R2 

BEQ END 

CER RE 

MOV R2,NUMC 


The command input is: 


MYPILE.MAC;:2/AU:50,MYFILE.LST=MYFPILE.MAC; 1] 
-2,.+1 
CMP (R1)+,B 
INC R2 
a 
In this example, the edit command, -2,.+1, instructs SLP to 


delete lines 2 and 3 and insert two new lines. 


SLP processing generates the following listing file (LISTING;1): 


1. MOV #BUF1,RO 

Due ACMP (Rij) ey 8 ; **NEW** 
35 LNG R2 PS eNEWA* 
44. Sk R2 pxk-2 

Se BEO END 

Os. -GOR Ra 

7. MOV R2,NUMC 
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10.3.4 Creating Source Files Using SLP 


Using SLP to create source files is possible, but Hoe 
recommended. SLP does not have an intraline editing mode and you 
cannot return to a line once you have passed it. An interactive 
editor, EDT, is better for creating source files. 


To create source files uSing SLP, invoke SLP and enter’ the 
command line in the format: 


outEile/-AU[/swi[f,listfile][/swl=[primary_input device:][/sw]] 
S J rans, t acted L / d 


| 


outfile 


The file specification for the output file. The default 
device is SY0Q:. 


/-AU 


Specifies that an audit trail is not to be generated. 
Otherwise, you will get the ;**NEW** audit trail on every 
line of the output files. 


listfile 


The file specification for the listing file (optional). The 
default device is implied by the output file specification. 


primary_input_device: 


Specifies that input for the file being created 1S coming 
from this device, for example, aterminal. The default 
device 1S your primary input device. 


{SW 
Specifies any optional SLP switches. 


The following file specification creates a new file called 
MYFILE.MAC from the terminal and puts it on SyY0:. 


MYFILE.MAC/-AU=TI: 

Once you have entered the file specification, SLP accepts’ each 
line aS a variable-length record of up to 132 (decimal) 
characters. Trailing blanks and tabs on input lines are deleted. 
SLP expects input to the file to come from the primary input 
device. End the SLP session with a slash (/) and then a CTRL/Z. 
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10.4 CONTROLLING SLP 


The SLP switches allow you to calculate the checksum value _ for 
the edit commands and to control the generation and format of the 
listing file and the output file. 


10.4.1 SLP Switches 


SEP: -OUtpUE “consists of two. files-<a listing file and the output 
File, which is the modified version of the input file. You can 
use the SEP switches to control the audit trail sand print options 
associated with the two files. 


The effects of SLP switches are the same whether you apply them 


to input or output files. Table 10-2 lists the SLP switches and 
gives a brief description of the functions each performs. 


Table 10-2: SLP Switches 


Switch Function 

/AU Allows you to generate an audit trail or suppress 

/-AU audit-trail generation and specify the beginning 
field and length of the audit trail. /AU is the 
default value. See the following sections for more 


information about the /AU switch. 


/BF Positions the audit trail by inserting spaces 
/-BFE instead of tabs at the end of text information. /BF 
is the default value. 


ZOMT en] Deletes audit trails and any trailing spaces or tabs, 
and truncates the text at a specified horizontal 
position. The value given for the beginning position 
of the audit trail is the default value for this 
Switch. See Section 10.4.6 for more information 
about the /CM switch. 


JEST AN) Calculates the checksum value for the edit commands. 
If you do not specify n, SLP reports the value ina 
message on your terminal. If you do specify n and 


the checksum value that SLP calculates is not the 
same as the one you specified, SLP displays a 
diagnostic error message. 
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Switch Function 


The procedure SLP uses to calculate the checksum 
value for the edit commands is described in Section 


oD 6 a Mere 
/DB Generates the listing file in double-space 
/-DB format. /-DB is the default value. 
/TR Reports truncation of lines by the audit trail. Lf 


line truncation occurs, you will get a diagnostic 
error message. There is no default value for this 
Switch. 


In the listing file, a question mark (?) replaces the 


period (.) in the line number of the lines that were 
truncated. 
/3Q sequences the lines in the output file so that the 


numbers reflect the line numbers of the original 
input file. New lines added to the file have the 
same number as the preceding line. This allows the 
MACRO Relocatable Assembler to output listing files 
that contain the original line numbers, thus easing 
the process of updating correction files. 


If you specify a listing file, SLP preserves the line 
numbers of the input file but does not display 
numbers for the new lines that have been inserted. 


JRS Resequences the lines in the output file so that the 
line numbers are incremented for each line written to 
the output file. The /RS switch overrides the /SQ 


Switch. 

/NS Does not sequence the lines in the output file. New 
lines are indicated by Che audit. “trait (1 
specified). The /NS switch is the default condition 


and overrides the /SQ and /RS switches. 


10.4.2 Controlling the Audit Trail 


The /AU switch allows you to generate, suppress, and set the 


length and contents of the audit trail. To suppress generation 
of the audit trail, specify the /-AU switch in either the input 
or output file specification. For example, either of the 


following command lines generates an output file with no audit 
Craid: 
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By default, SLP automatically generates an audit trail; that is, 
you need not explicitly specify the /AU switch in your command 
line (unless you want to specify the beginning position and 
length of the audit trail). 


10.4.3 Setting the Position and Length of the Audit Trail 


You can set the beginning position of the audit trail and the 
length of the audit trail using the /AU switch in the format: 


position 


A number, less than or equal to 132 (decimal), designating 
the beginning character position of the audit trail on the 
line. SLP rounds this value to the next highest tab stop (a 
multiple of 8). The default value for position is 80 
(decimal). 


NOTE 


Numeric values given for switches default to octal. 
Decimal values must be followed by a period (.). 
The default position for the audit trail is 80 
(decimal) and its default length is 8 (decimal); no 
more than 14 (decimal) characters may be specified. 
(See Section 10.4.2 for more information about the 
audit trail.) 


length 


The length of the audit trail. The default value for length 
is 8 (decimal) characters; no more than 14 (decimal) 
characters may be specified. 


The following example shows how to specify the beginning position 
and length of the audit trail. The input file for this example 
is: 


MOV #BUF1,RO 
MOV #512 ,R1 
CALL READ 

TST RZ 

BEQ BEND 
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The command input is: 


MYFILE.MAC;2/AU:30.:10./TR,MYFILE.LST=MYFILE.MAC;1 
~2,.+1,/;CHANGE0N01/ 
(R1)+,B 


CMP 
DEC 


a 


R2 


The lusting file MYFILE.UST?;1 resulting Prom -SLP-processing is: 


1. MOV 
Zu: KEMP 
S35. ‘DEC 
a. “St 
S54. “BEC 


#BUF1,RO 

(R1)+,B * CHANGEOO1 
R2 * CHANGEOO1 
R2 sk x2 

END 


10.4.4 Changing the Value of the Audit Trail 


To change the value of the audit trail, specify: 


~{locatori],[locator2],/;new value/ 


The following example shows how to change the audit trail values. 
The input file consists of the following lines: 


MOV 
MOV 
CALL 
vipewe 
BEQ 
CLR 
MOV 
CMPB 
BNE 
INC 


#BUF1,RO 
#512Z,R1 


READ 


R2 
END 
Ri 


R2,NUMC 
(RO)+,A 


20$ 
R1 


The command input consists of the following commands and text 


lines: 


MYFILE.MAC;2/AU:48.:10./TR,MYFILE.LST/-SP=MYFILE.MAC;1 


-3 

CMP (R1)+,B 
-~-4,4 

DEC R2 
-6,,/;IM010/ 
LNG R3 
-9,,/;BJ008/ 
BEQ 10$ 

re 
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In this example, the edit commands instruct SLP to insert a line 
after line 3, to delete and replace line 4, and to insert new 
lines after lines 6 and 9 with new audit trail values. 


The listing file (MYFILE.LST) resulting from SLP processing 
appears as follows: 


le: MOV #BUF1,RO 

23 . MOV #S5IZ,R1 

3. CALL READ 

4, CMP (R1)+,B ; **NEW** 
5a: DEC R2 > k kNEW* * 
6. BEQ END ol 

va CLR R1 

8. INC R3 ;JIM010 
9. MOV R2,NUMC 
10. CMPB (RO)+,A 
11. BNE 20$ 
L233, BO 10$ ;BJ008 
he 3% INC R1 


10.4.5 Temporarily Suppressing the Audit Trail 


You can temporarily suppress the generation of the audit trail by 
using the backslash (\) operator. You can then reenable 
audit-trail processing with the percent sign (%) operator. (You 
cannot enable audit trail processing with this operator if you 
have specified the /-AU switch in the SLP command line.) 


Both operators are entered in the command input. The backslash 
(\) is specified in column 1 of the line that precedes those 
commands and/or input files for which you do not want audit-trail 
processing. The percent sign (%) is Specified in column 1 of the 
line that precedes the lines for which you do want = processing. 
For example: 


BAK.MAC;26/AU/-BF=BAK.MAC;25 


‘ 
Lge 
-IDENT /05.03/ 
a2 pao 
e VEROLON 05.035 
eae , 
; J. MATTHEWS 11-NOV-80 
; 
; JMOQ1i1 CORRECT OUT=OF =BOUNDS CONDITION “FOR 
LINPUL=BUPE AR 
; SIZE 
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9 
6 


2106 420657 -IMOLLy 


CMP St ie ge © , IS INPUT-BUFFER SIZE IN RANGE? 
BLT 30S e aE Teiee:. “INO 
/ 
The lines between the backslash (\) and the percent sign (%) are 


not affected by audit-trail processing. The lines following the 
percent sign (%) are affected. 


10.4.6 Deleting the Audit Trail 


The /CM switch allows you to delete audit trails and trailing 
Spaces and tabs from a file. The /CM switch applied to the 
output or input file specification acceptS a numeric argument 
that specifies the beginning position of an audit trail or other 
text. String co be deleted... The default. tor this argument is the 
position argument given for the /AU switch (or its default, 
decimal 80). This value is rounded to the next highest tab stop 
before use. 


When processing an input line, SLP first truncates the text to 
the next highest tab stop after the position specified, and then 
deletes any trailing spaces or tabs. The remaining text is 
copied to the output file. 

The /CM switch is specified in the form: 


JCMS Lay] 


A number designating the beginning character position of the 
audit trail (or other text) to be deleted. 


For example: 


SLP>SLPR11.MAC;12/CM:119.=SLPR11.MAC;11 


a 
In this case, the input lines are truncated to a length of 120 
(decimal) characters. The specified length is rounded up to the 
next highest tab stop and the audit trail begins at column 121 
(decimal). Trailing spaces and tabs are deleted before each line 


is copied to the output file. 
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In the following example, SLP truncates input lines to the 
default position of the audit trail, column 80 (decimal). 


SLP>SLPR1i1.MAC;12=SLPR11.MAC;11/CM 
/ 


10.5 SLP MESSAGES 
SLP messages are divided into two groups: information and error. 
The messages and suggested responses are given in the following 


sections. Section 10.5.1 describes the information message and 
section 10.5.2 describes the error messages. 


10.5.1 SLP Information Message 

SLP -- COMMAND FILE CHECKSUM IS ###### 
Explanation: By specifying the /CS[:n] switch in the 
command line, you requested SLP to calculate the checksum 


value for the edit commands. 


User Action: This message is for your information only. No 
action is required. 


10.5.2 SLP Error Messages 


This section lists the SLP error messages. Following each 
message is an explanation of the error and recommended user 


action to correct the error. 


SLP error messages are issued in two formats: 


o SLP followed by a dash, the type of error message, and _ the 


error message. If applicable, the command line or command 
line segment that caused the message is printed on the next 
line. For example: 

SLP -- *FATAL*-ILLEGAL SWITCH OR FILESPEC 


SHIRLEY.MAC;2/CF 


o SLP followed by a dash, the type of error message, the error 


message, and the name of the file with which the error is 
associated. For example: 
SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename 
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Note that all but two of the SLP error messages are fatal. The 


two exceptions are diagnostic messages, which are described at 
the end of this section. 


SLP -- *FATAL*-COMMAND SYNTAX ERROR 

command line 
Explanations The command line format did not conform to 
syntax rules. Open files were closed and SLP was 
reinitialized. 
User Action: Reenter the command line, specifying the 
proper syntax. 

SLP -- *FATAL*-ILLEGAL DEVICE NAME 


command line 


Explanation: The device specified was not a legal device. 
Open files were closed and SLP was reinitialized. 


User Action: Reenter the command line, specifying a legal 
device. 
SLP -- *FATAL*-ILLEGAL DIRECTORY 


command line segment 


Explanation: The directory was not legally specified. Open 
files were closed and SLP was reinitialized. 


User Actions Reenter the command line, specifying a legal 
directory. 
SLP -- *FATAL*-ILLEGAL ERROR/SEVERITY CODE pi p2 p3 


Explanation: This error message indicates an error in the 
SLP program. 


User Actions: Reenter the command line. If this does not 
correct the problem, call your DIGITAL Customer Support 
Center. 

SLP -- *FATAL*-ILLEGAL FILE NAME 


command line segment 


Explanation: A file specification was greater than 19 
(decimal) characters in length or contained a wildcard (that 
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1s, an asterisk in place of a file specification element). 
Open files were closed and SLP was reinitialized. 
User Action: Reenter the command line, specifying a legal 
filename. 
SLP -- *FATAL*-ILLEGAL GET COMMAND LINE ERROR 
Explanations The system was unable to read a command line. 


This error message indicates an internal system failure or 
an error in the SLP program. 


User Actions: Reenter the command line. If this does not 
correct the problem, call your DIGITAL Customer Support 
Center. 

SLP -- *FATAL*-ILLEGAL SWITCH OR FILESPEC 


command line segment 


Explanation: The switch was not a legal SLP switch or a 
legal switch was used in an illegal manner, ora file 
specification could not be parsed. 


User Action: Reenter the command line, specifying the legal 
Switch, or correct the file specification. 


SLP -- *FATAL*-INDIRECT COMMAND SYNTAX ERROR 
command line 


Explanations: The command line format specified for the 
indirect command file did not conform to syntax rules. Open 
files are closed and SLP was reinitialized. 


User Actions Reenter the command line, specifying the 
proper syntax. 


SLP -- *FATAL*-INDIRECT FILE DEPTH EXCEEDED 
command line 


Explanation: More than three levels of indirect command 
files were specified in an indirect command file. Open 
files were closed and SLP was reinitialized. 


User Actions: Correct the indirect command file and reenter 
the command line. 
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SLP -- *FATAL*-I/0 ERROR COMMAND INPUT FILE 
or 
OLP -- *FATAL*-I/Q ERROR COMMAND OUTPUT FILE 
or 
SLP -- *FATAL*-I/0O ERROR CORRECTION INPUT FILE filename 
or 
SLP -- *FATAL*-I/O ERROR LINE LISTING FILE filename 
or 
SLP -- *FATAL*-I/O ERROR SOURCE OUTPUT FILE filename 


Explanations One of the following conditions may exist: 
® A problem exists on the physical device. 


® The length of the command line was greater than _ the 
allowed number of characters. 


e The file is corrupted or the format is incorrect. 


User Actions: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


SLP -- *FATAL*-INDIRECT FILE OPEN FAILURE 
command line 


or 

SLP -- *FATAL*-OPEN FAILURE CORRECTION INPUT FILE filename 
or 

SLP -- *FATAL*-OPEN FAILURE LINE LISTING FILE filename 
or 

SLP -- *FATAL*-OPEN FAILURE SOURCE OUTPUT FILE filename 


Explanation: One of the following conditions may exist: 
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® The file is protected against an access. 

@ A problem exists with the physical device 

@ The volume is not mounted. 

® The specified file directory does not exist. 


® The named file does not exist in the specified 
GLrectory:. 


@ The available Executive dynamic memory is insufficient 
for the operation. 


These errors cause open files to be closed and SLP to _ be 
reinitialized. 


User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


SLP -- *FATAL*-LINE NUMBER ERROR 
command line 


Explanations The command line printed contained an 
illegally specified numeric line locator. 


User Actions: Terminate the SLP edit session and refer to 
the rules for specifying numeric line locators in Section 
10.3.1. Correct the error and reenter the command line. 


SLP -- *FATAL*-PREMATURE EOF CORRECTION INPUT FILE filename 


Explanations An out-of-range line locator was specified in 
an indirect command file or from the terminal; for example, 
-990 was specified for an 800-line file. 


User Actions: Terminate the current editing session. 
Restart the editing session, and enter the edit command 
line, specifying the correct line number. 


SLP -- *FATAL*-PREMATURE EOF COMMAND INPUT FILE 


Explanations This is caused by not terminating SLP command 
input with a slash (/) or by inadvertently typing CTRL/Z at 
the terminal, which sends an end-of-file to SLP before the 
slash (/) ¢haracter 1S réad: SbLP. prompts (SEP>), indicating 
that a new file specification is expected. 
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User Action: Restart the editing session at the point where 
the CTRL/Z was typed. 


SLP -- *DIAG*-ERROR IN COMMAND FILE filespec CHECKSUM 


Explanations An incorrect value was specified for the 
command file checksum. If you enter the edit command lines 
directly from the terminal, the command file in the error 
message is CMI.CMD. Thus, the error message reads: 


SLP -- *DIAG*-ERROR IN COMMAND FILE CMI.CMD CHECKSUM 


User Action: This iS a warning message only. The specified 
output file is still created, although possibly not as 
intended. 


SLP -- *DIAG*-n LINES TRUNCATED BY AUDIT TRAIL 
command line 


Explanation: Line truncation by the audit trail was 
detected. 


User Action: This is an informational message only. The 
Specified output file is still created. (In the listing 
file, a question mark (?) replaces the period (.) in _ the 
line number of the lines that were truncated. it 2S 
possible that audit-trail strings from the input file will 
be truncated by the new audit-trail string although text 


strings will not be truncated.) Determine where the 
truncation(s) occurred. If necessary, modify the command 
file so that it contains commands that do not cause 
truncation. 
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The Convert Utility (CVT) provides you with a convenient means of 
converting an integer value into several different radixes. 


To invoke CVT, enter the following command from DCL: 
S RUN SCVT 
You receive the following prompt: 
CVT> 
Once you receive the CVT prompt, you can enter an integer 


expression. Figure 11-1 illustrates the output of CVT when you 
enter the value 15 (octal). 


S RUN SCVT ! Execute the Convert Utility. 
CVT> i5 
136 A2S6¢0s 000015 015,000 Ss000D % M "<CR ><NUL> 


ff I tf ft Tf fT 


Decimal Decimal Octal Octal Hex RAD50 ASCII 
Word Bytes Word Bytes Word Word Bytes 


Figure 11-1: Output of the CVT Utility 


CVT displays a row of numbers that represent the value 15 (octal) 
converted into a decimal word, decimal bytes, octal word, octal 
bytes, hexadecimal word, RAD50 word, and ASCII bytes. 


Le 


CONVERE: UTE ETY 


By default, CVT interprets the expression you specify as an octal 
value. However, you can force CVT to interpret the expression as 
decimal, hexadecimal, RAD50, or ASCII. To do this, you use the 
punctuation described in Table 11-1. Note that CVT uses the same 
punctuation in its output display to indicate the radix of each 
value. 


Table 11-1: Punctuation to Specify Radix 


Name Example Description 


Period i oe Forces decimal interpretation. Place 
the period immediately after the 
value you want interpreted as 


decimal. 
Dollar 5) Forces hexadecimal interpretation. 
Sign Place the dollar sign immediately 


before the value you want 
interpreted as hexadecimal. 


fe\\e) 
= 


Percent Forces RAD50O interpretation. Place 

Sign the percent sign immediately before 
the value you want interpreted as 
RADS5SO. You can enter from one to 
three RADS5O characters at a time. 


Apostrophe 'x Forces ASCII interpretation of 1 
byte. Place the apostrophe 
immediately before the value you 
want interpreted as an ASCII byte. 
You can enter no more than one 
character after an apostrophe. 


Quotation “xx Forces ASCII interpretation of two 

Mark bytes. Place the quotation mark 
immediately before the value you 
want interpreted as two ASCII bytes. 


Li=2 


CHAPTER 12 
PERIPHERAL INTERCHANGE PROGRAM (PIP) 


The Peripheral Interchange Program (PIP) is a file utility 
program that transfers data files from one standard FILES-11 
device to another. PIP also performs file control functions. 
Some of the functions PIP performs are: 

® Copying files from one device to another 

@ Deleting files 

® Renaming files 

@ Listing file directories 


® Setting the default device and UIC for PIP operations 


® Unlocking files 


12.1 INVOKING PIP 

You can invoke PIP in two ways: 

1. Invoke the DCL commands that manipulate files; these commands 
in turn invoke PIP. See Section 1.1.1 for a list of 
file-handling commands. 

2. Invoke PIP directly from the DCL command level. 

To invoke PIP directly from the DCL command level, enter the 


following command: 


S RUN SPIP 
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You receive a new prompt to indicate that you are in the PIP 
environment: 


PIP> 


Once you are in the PIP environment, PIP waits for your command. 
The following section describes the command format. 


12.2 FORMAT OF PIP COMMANDS 

The simplest format for the PIP command line is: 
outfile=infile 

outfile 


The output file specification. If the output filename, file 
Cype,, and -version are. either defaulted or *,.*;*, the input 
filename, file type, and version are used for the output 
file (see /NV and /SU subswitches). 


If you explicitly specify any portion of the output file 
Specification (filename, file type, or version), wildcards 
cannot be used in this specification. 


Similarly, for a copy command, if you enter any portion of 
the output specification, you can enter only one file as the 
Inpuc. £4.le% 

infile 


The input file specification. If the filename, file type, 
and version fields are not specified, then *.*;* is the 


default. 
One switch that you can specify when copying FILES-11 files is 
the Merge switch (/ME). The Merge switch creates a new file from 
two or more existing files. PIP assumes /ME when you explicitly 


specify an output file, two or more input files, and no switches. 
Because the basic copy function and the Merge switch are 
logically related, the Merge switch is described here rather than 
with the other switches. 

The general format of the PIP command line is: 


outfile=infilel[{,infile2...,infilen][[/ME][/subswitch] |] 
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outfile 


The output file specification. 


infile 


The input file specification. 


/ME 


The Merge switch. 


/subswitch 


Specifies any of the subswitches that you can enter as part 
of the basic command line or with the Merge switch. (Table 
12-2 describes these subswitches. ) 


Subswitches can appear in either the output or input file 
specification. If you place the subswitch in an input file 
specification, it applies only to that file. If you place 
the subswitch in the output file specification, it applies 
to the entire list of input specifications. 


12.3. PIP DEFAULTS FOR FILE SPECIFICATION FIELDS 


With the exception of the version number, PIP generally uses’ the 
last value encountered in the command line as the default. That 
is, PIP uses values you enter to set defaults and changes’ the 
default when you change the value. Exceptions to this are noted 
in the descriptions of each switch. 


In the following example, T1.MAC;5 sets the defaults for’ the 
subsequent file specifications in the command line. Then, T2 is 
specified and overrides T1 as the default filename; however, .MAC 
remains the default file type. Finally, .TSK is specified, which 
overrides .MAC as the default, while T2 remains the default 
filename. 


Note, in this example, that the version number does not default. 
PIP>T1.MAC;5,T2,.TSK/BR 
Ti.MAC;5 


T2.MAC;1 
C22SK3 


L235 


PLP DEFAULTS: FOR. FILE. SPECIFICATION FIELDS 


Table 12-1 summarizes the rules PIP uses to set defaults. 


Table 12-1: PIP Default File Specifications 


Field Default Value 
dev: For the first file specification, the unit on 
which the user’s system disk is mounted (SyYO:) or 


the default that you specify with the /DF switch. 


For subsequent file specifications, either you 
explicitly specify a new device or PIP assumes the 
device from the previous specification. 


[ufd] For the first file specification, your current 
User Identification Code (UIC)--the UIC under 
which you log on, the UIC you specify with the SET 
command, or the default you specify with the /DF 
Switch. 


For subsequent file specifications, either you 
explicitly specify a new User File Directory or 
PIP assumes the UFD from the previous 
specification. Only the asterisk specification is 
valid as a wildcard. 


filename No default for the first file specification. For 
subsequent file specifications, the last file name 
that you explicitly specified. Asterisk and 
percent sign specifications are valid as 
wildcards. 


Le LLecy oe No default for the first file specification. For 
subsequent file specifications, the last file type 
that you explicitly specified. Asterisk and 
percent sign specifications are valid as 
wildcards. 
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Field Default Value 


;version The default for input files is the most recent 
version number. The default for output files is 
the next higher version number, or version 1 if 
the file does not exist in the output directory. 
An exception is the PIP file delete function, 
which requires that a version number be specified. 


An explicit version number is defined to be of the 
form ;n where n is greater than 0. A version 
number of ;-1 may be used to specify the oldest 
version of a file. A version number of ;0 or ; may 
be specified to signify the most recent version. 
In certain cases, just the asterisk (wildcard) may 
be specified. 


12.4 PIP SWITCHES AND SUBSWITCHES 


PIP provides several file control switches and subswitches. A 
Switch specification consists of a slash (/) followed by a two- 
or three-character switch name. 


The switch specification is optionally followed by a $subswitch 
name separated from the switch name by a slash. The switch or 
subswitch can have arguments that are separated from the switch 
or subswitch name by a colon (:). 


To allow several commands to be performed consecutively, more 
than one command can be specified in a line. To separate each 
command, the ampersand character (&) is used. 


Most of the PIP switches operate on lists of file specifications. 
The exceptions are /DD, /DF, /ID, and /TD, which are used by 
themselves. 


Table 12-2 lists PIP switches and subswitches and summarizes the 
functions performed by them. The subswitches are listed with 
their respective switches. The switches and subswitches are 
described in detail in Section 12.4.1. 
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Table 12-2: PIP Switches and Subswitches 


Switch Subswitch 
/AP 
FO 
/CD 
DE 
LD 
DD 
DF 
EN 
NV 


EOF[:block:byte] 


EX 


/FI:filenum:seqnum 


FR 


LD 


Function 


Appends file(s) to the end of an 
existing file. 


Specifies the file owner for a file. 


Allows the output file to take the 
creation date of the input file rather 
than the date of transfer. 


Deletes one or more files. 
Lists the deleted files. 


Restricts file searches to files 
created during a specified period of 
time. 


Changes PIP’s default device and/or 
UFD. 


Enters a synonym for a file ina 
directory file. 


Forces the version number of a file to 
one greater than the latest version. 


Specifies the end-of-file pointer for 
a file. 


Excludes one file specification from 
the PIP operation. 


Accesses a file by its file 
identification number (file-ID). 


Displays the amount of available space 
on the specified volume, the largest 
contiguous free space on that volume, 
and the number of available file 
headers. 


Identifies the version of PIP being 
used. 
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LI 


ME 


NM 


/PR 
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Subswitch 


BR 


TB 


BL:n[. ] 


ce 


FO 


NV 


SU 


FO 


GR[ :RWED] 


OW[ : RWED ] 


SY[:RWED] 


Function 
Lists directory files. 


Lists a directory file in brief format 
(an alternative mode for the /LI 
Switch). 


Lists a directory file in full format 
(an alternative mode for the /LI 
Switch). 


Lists the total number of blocks used 
for a directory, along with the total 
number of blocks allocated and the 

number of files in that directory (an 
alternative mode for the /LI switch). 


Concatenates two or more files into 
one file. 


Allocates a number (n) of contiguous 
blocks. 


Specifies that the output file(s) be 
contiguous. 


Specifies the file ownership for a 
file. 


Forces the version number of a file to 
one greater than the latest version. 


Supersedes (replaces) an existing 
file. 


Suppresses certain PIP error messages. 


Changes the protection status of a 
file. 


Specifies the ownership for a file. 


Sets the read/write/extend/delete 
protection at the group level. 


Sets the read/write/extend/delete 
protection at the owner level. 


Sets the read/write/extend/delete 
protection at the system level. 
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Switch Subswitch Function 
WO[ :RWED ] Sets the read/write/extend/delete 
protection at the world level. 
GEOL AD (si) Deletes obsolete version(s) of a file. 
LD Lists the deleted files. 
RE Renames a file. 
RM Removes a file entry from a directory. 
SD Selectively deletes files by prompting 


for your response before deleting. 


SR Allows shared reading of a file that 
has already been opened for writing by 
another user or task. 


TD Restricts file searches to files 
created on the current day. 


TR Truncates. files to logical 
end-of-file. 


UF Creates a User File Directory entry on 
the volume to which a file is being 
transferred. 


UN Unlocks a file. 
UP Updates (rewrites) an existing file. 
FO Specifies the owner for a file. 


12.4.1 Switches 


PIP accepts some switches with no file specification. However, 
when you use a switch in a command line, it must follow the file 
or directory specification. It cannot come before the device 


name, the directory, the filename, file type, or version of the 
file: “Om Which 120 18° °to operate. 


You may specify a switch once for a list of file specifications. 
For example: 
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fFilespeci,filespec2,filespec3/DE 


The /DE switch applies to all of the file specifications. PIP 
deletes every specified file from its UFD. 


You specify switch arguments as octal (default), decimal, or 
alphabetic characters, depending on the switch. The sections 
that explain the individual PIP switches discuss these values. 


12.4.2 Subswitches 


You can apply subswitches to one or more file specifications, 
depending on the placement of the subswitch. Subswitches can 
appear in either the output file specification or the input file 
specification. 


If you place the subswitch in the output file specification, the 


subswitch applies EO the entire Last Of input file 
specifications. For example, the Contiguous Output switch (/CO) 
is applied to both TEST.TSK and SAMP.DAT. (The /CO switch is 


used with the Copy function.) 
PIP>/CO=TEST.TSK;1,SAMP.DAT;1 


PIP copies TEST.TSK;1 and SAMP.DAT;1 such that the copies, 
TEST.TSK;2 and SAMP.DAT;2, are contiguous. 


If you place the subswitch in the input file specification, it 
usually applies only to the file specification that immediately 
precedes it. In the following example, the New Version subswitch 
(/NV) is applied to the file ASDG.MAC. (The /NV subswitch is 
being used with the Rename switch, /RE.) 


PIP>*.SMP=PRT2.QRT,ASDG.MAC/NV,KG.MAC/RE 


PIP renames the files PRT2.QRT and kKG.MAC, but they maintain 
their associated version numbers. File ASDG.MAC is also renamed, 
but the version number is forced to a number one greater than the 
latest version of file ASDG.SMP (assuming a version of ASDG.SMP 
already exists). 


When you explicitly apply a subswitch to a file specification, 
you implicitly apply the switch with which the subswitch is 
associated. On a command line with more than one file 
specification, the explicit subswitch affects only the file to 
which it is applied. The implicit switch affects all the files 
on the command line. 
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Example 
PIP>FILE1.CMD/GR:R/WO, FILE2.MAC/GR:Rh 
This command is equivalent to: 
PIP>FILE1.CMD/GR:R/WO, FILE2.MAC/GR:RW/PR 


The command results in the following file protection: 


a. FILE1 SYSTEM -- Unchanged 
MEMBER -- Unchanged 
GROUP -- Read access 
WORLD -- No access 
Dw FILEZ SYSTEM -- Unchanged 
MEMBER -- Unchanged 
GROUP -- Read/write access 
WORLD -- Unchanged 


12.5 SPECIFYING WILDCARDS 


PIP allows you to specify wildcards in file specifications. The 
wildcard characters are the asterisk (*) and the percent sign (%) 
characters. You can use both wildcards in place of explicit 
specifications for filenames and file types. Use only the 
asterisk wildcard in place of file directories and version 


numbers. 


The asterisk can denote zero or more characters in the field you 
Specify it in, while the percent sign character denotes a single 


character in afield. (Correct syntax must _ be followed, 
however. ) 
Wildcards are restricted in some cases. The following sections 


describe and give examples of wildcards in input and output file 
specifications. 


12.5.1. Wildcards in Output File Specifications 
Wildcards in the output file specifications are restricted. For 


the following PIP functions, the output file specification cannot 
have any wildcards: 
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® Concatenating files to a specified file 

@ Appending files to an existing file 

® Updating (rewriting) an existing file 

e Listing a directory 

If you use wildcards in the output file specification for any of 
these functions, the meaning of the command line would be 
ambiguous. For example: 


PIP>LIST.*=([USERFILES]/LI 


You have incompletely specified the output file specification. 
PIP returns an error message. 


When you make copies of several files, the output specification 
must be *.*;* or defaulted from the input file specification(s). 


For the Rename (/RE) and Enter (/EN) switches, the output 
specification may have wildcards (asterisk only) mixed with 
specified fields. For either switch, the equivalent field of the 
input file specification is used. 


For all cases in which wildcards are allowed in the output file 
specification, the wildcard directory form [*] is used to 


indicate that the output directory is to be the same as the input 
directory. 


NOTE 


ie) 


The percent sign (%) cannot be used in = output 
file specifications. 


12.5.2 Wildcards in Input Specifications 


PIP provides the following wildcard features for input file 
specifications: 


® *.*;* means all versions of all files. 


o *.DAT;* means all versions of all files of file type .DAT. 
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*.D*;* means all versions of all files with file types 
beginning with D. 
TEST.*;* means all versions of all types of files named TEST. 


T*.*;* means all versions of all types of files with names 
beginning with T. 


TEST.DAT;* means all versions of file TEST.DAT. 
TEST.D%T;* means all versions of files named TEST with 
three-character file types beginning with D and ending with 


pia 


TON.*;* means all versions of all file types of all 
three-character filenames beginning with T and ending with N. 


k*,* means the most recent version of all files. 


* DAT means the most recent version of all files of file type 
.DAT. 


*%.DAT means the most recent version of all files that have 
at least one character in their names and have the file type 
of .DAT. 

TEST.* means the most recent version of all file types for 
files named TEST. 


also provides the following wildcard directory features: 


[*,*] means all group,member number combinations (1 to 377 
octal) 


[ni,*] means all member numbers under group nil. 
[*,n2] means all group numbers for member n2. 


[*] means all directories. 


NOTE 


The percent sign (%) character cannot be used in 
the directory. 
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12.6 PIP ERROR MESSAGES 


The PIP error messages, their descriptions and suggested user 
actions are as follows: 


PIP -- ALLOCATION FAILURE - NO CONTIGUOUS SPACE 


Explanation: Not enough contiguous space was available on 
the output volume for the file being copied. 


User Action: Delete all files that are no longer’ required 
on the output volume, then reenter the command line. 


PIP -- ALLOCATION FAILURE ON OUTPUT FILE 
or 
PIP -- ALLOCATION FAILURE - NO SPACE AVAILABLE 


Explanations Not enough space was available on the output 
volume for the file being copied. 


User Action: Delete all files that are no longer required 
on the output volume, then reenter the command line. 

PIP -- BAD USE OF WILD CARDS/CHARACTERS IN DESTINATION FILE NAME 
Explanation: A wildcard/character was specified for an 
output filename when use of a wildcard/character was 
explicitly disallowed. 

User Action: Reenter the command line with the output file 
explicitly specified. 

PIP -- CANNOT EXCLUDE *.*;* 


Explanation: The /EX switch does not accept all wildcards 
as the input file specification. 


User Action: Determine the files to be excluded and reenter 
the command line. 
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PLP) == CANNOT FIND DIRECTORY (FILE 


Explanation: The specified directory does not exist on the 
volume. 


User Actions Reenter the command line, specifying the 
correct directory or the correct volume. 
PIP -- CANNOT FIND FILE(S) 


Explanation: The file(s) specified in the command line 
was(were) not found in the designated directory. ae 


User Actions: Check the file specification and reenter’ the 
command line. 

PIP -- CANNOT RENAME FROM ONE DEVICE TO ANOTHER 
Explanation: You attempted to rename a file across devices. 
User Actions: Reenter the command line, renaming the file on 
the input volume, then enter another command to transfer the 
file to the intended volume. 

PIP -- CANNOT TRUNCATE THIS FILETYPE 


Explanation: PIP can only truncate files containing 
fixed-length, variable-length, and sequenced records. 


User Action: Check the file specification and reenter’ the 
command line. 


PIP -- CLOSE FAILURE ON INPUT FILE 


or 
PIP -- CLOSE FAILURE ON OUTPUT FILE 


Explanation: The input or output file could not be properly 
closed. If the failure is on the output file, the output 
file is then locked to indicate possible corruption. 


User Actions Reenter the command Iline. If the error 
recurs, run a validity check of the file structure using the 
File Structure Verification Utility (VFY) on the volume in 
question to determine if it 1s corrupted. 
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COMMAND SYNTAX ERROR 


User Actions Reenter the command 
syntax. 


Explanation: 
was not mounted, 


User Actions: 


DEVICE NOT MOUNTED/ALLOCATED 


then reenter the command line. 


Explanation: 


DIRECTORY WRITE PROTECTED 


line 


Allocate the drive and/or 


with 


The drive had not been allocated, 


mount 


because the device was write-protected or 
privilege violation. 


User Actions: 
the owner of 


Explanation: 


ERROR FROM PARSE 


the 


the 


the 


Command did not conform to syntax rules. 


correct 


device 


or another user had mounted the device. 


device, 


PIP could not remove an entry from a directory 


because of a 


Enable the device for write operations or have 
the directory change its protection. 


The specified directory file does not exist. 


User Action: Reenter the command line with the correct UIC 
specified. 


EXPLICIT OUTPUT FILENAME REQUIRED 


Explanation: Self-explanatory. 


User Action: Reenter the command 
filename explicitly specified. 


FAILED TO ATTACH OUTPUT DEVICE 


or 


FAILED TO DETACH OUTPUT DEVICE 
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Explanation: An attempt to attach/detach a record-oriented 
output device failed. This is usually caused by the device 
being off-line or nonresident. 


User Actions Ensure that the device is on-line and reenter 
the command line. 


PIP ~-- FAILED TO ATTACH TERMINAL 


Explanation: PIP could not attach a terminal, probably 
because of a privilege violation. 


User Actions Determine the cause of the failure and correct 
it. Reenter the command line. 


PIP -- FAILED TO CREATE OUTPUT directory 


Explanation: PIP could not create an entry in a directory 
because the device wasS write-protected or because of a 
privilege violation. 


User Actions Enable the unit for write operations or have 
the owner of the directory change its protection. 


PIP -- FAILED TO DELETE FILE 
or 
PIP -- FAILED TO MARK FILE FOR DELETE 


Explanations You attempted to delete a protected file. 
User Action: Change the protection of the file if possible, 
and reenter the command line. 

PIP -- FAILED TO ENTER NEW FILE NAME 
Explanation: You specified a file that already exists in 
the. directory file, or you did not nave the necessary 


privileges to make entries in the specified directory file. 


User Action: Reenter the command line, ensuring that the 
filename and directory are specified correctly. 
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Pip == PATLED “TO. FIND FILE GS) 


Explanation: The file(s) specified in the command line 
waS(were) not found in the designated directory. 


User Action: Check the file specification and reenter the 
command line. 
PIP =-- FAILED TO GET TIME PARAMETERS 


Explanation: An internal system failure occurred while PIP 
was trying to obtain the current date and time. 


User Action: Reenter the command line. If the problem 
persists, submit a Software Performance Report (SPR). 


PIP == FALLED ‘TO. OPEN:-INDEX FILE 


Explanations PIP was unable to read the index file, 
probably because of a privilege violation. 


User Action: Retry the operation by running PIP under a 
system UIC, or have the system manager change the protection 
on the index file. 


PIP -- FAILED TO OPEN STORAGE BITMAP FILE 


Explanation: PIP could not read the specified volume’s 
storage bitmap, probably because of a privilege violation. 


User Action: Retry the operation by running PIP under a 
system UIC, or have the system manager change the protection 
on the storage bitmap. 


PIP -- FAILED TO READ ATTRIBUTES 


Explanation: The volume you specified was corrupted or you 
did not have the necessary privileges to access the file. 


User Actions Ensure that PIP is running under the correct 
UC. If the UIC is correct, then run the validity check 
using the File Structure Verification Utility (VFY) against 
the volume in question to determine where and to what extent 
the volume is corrupted. 
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PIP == PAITGED: “fO..REMOVE: DIRECTORY ENTRY 


Explanations PIP could not remove an entry from a directory 
because the unit waS write-protected or because of a 
privilege violation. 


User Actions Enable the unit for write operations or have 
the owner of the directory change its protection. 


PIP -- FAILED TO RESTORE ORIGINAL DIRECTORY ENTRY - FILE IS LOST 


Explanation: PIP has removed a file from a directory, 
failed to enter it (using /RE) into another directory, and 
Failed to replace the original directory entry. 


User Actions Run the lost check of the File Structure 
Verification Utility (VFY) to recover the filename. 


PIP -- FAILED TO TRUNCATE FILE 


Explanation: The volume you specified is corrupted or _ you 
did not have the necessary privileges (write, extend) to 
truncate this file. 


User Actions Ensure that PIP iS running under the correct 
ULC. If the UIC is correct, then run the validity check of 
the File Structure Verification Utility (VFY) against the 
volume in question to determine where and to what extent the 
volume is corrupted. 


PIP -- FAILED TO WRITE ATTRIBUTES 


Explanation: The volume you specified is corrupted or you 
did not have the necessary privileges to write the file 


attributes. 


User Actions Ensure that PIP is running under the correct 
UPC- If the UIC 1S correct, then run the validity check of 
the File Structure Verification Utility (VFY) against the 
volume in question to determine where and to what extent the 
volume is corrupted. 
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Bab es PE don OS 
Explanation: PIP has removed a file from its directory, 
failed to delete it, and failed to restore the directory 
entry. 
User Action: Run the lost check of the File Structure 
Verification Utility (VFY) to recover the filename. 


PIP ee PEE NOT LOCKED 


Explanation: The /UN switch was entered for a file that was 
not locked. 


User Action: Reenter the command line, specifying the 
correct file. 
PIP -- GET COMMAND LINE - BAD @ FILE NAME 


Explanations An illegal indirect command filename was 
specified. 


User Action: Reenter the command line, specifying the 
correct name for the indirect command file. 
PIP - GET COMMAND LINE - FAILED TO OPEN @4 FILE 


Explanations: PIP could not find the specified indirect 
command file. 


User Action: Check the specification for the indirect 
command file and reenter the command line. 
PIP -- GET COMMAND LINE - I/O ERROR 


Explanation: An I/O error occurred during an attempt to 
read a command line. 


User Actions Check the command to ensure that you entered 
it correctly, then reenter the command line. If the error 
persists, submit a Software Performance Report (SPR). 


PIP -- GET COMMAND LINE - MAX @ FILE DEPTH EXCEEDED 


Explanations The maximum level of nesting for indirect 
command files (4) was exceeded. 
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User Actions: Reduce the level of nesting. 


PIP -- ILLEGAL COMMAND 
Explanation: The command was not recognized by PIP. 


User Action: Reenter the command line with the PIP command 
correctly specified. 


PIP -=- ILLEGAL EOF VALUE 


Explanation: You specified an illegal block and/or byte 
value in the command line. 


User Actions Reenter the command line with the correct 
values. 


PIP -- ILLEGAL RESPONSE - TRY AGAIN 
Explanation: Self-explanatory. 


User Actions: Check which response you want and enter it 
when PIP prompts you. 


PIP -- ILLEGAL SWITCH 


Explanation: The specified switch was not a legal PIP 
SWi Ucn. 


User Action: Reenter the command line with the correct 
Switch specification. 


PIP -- ILLEGAL "*" COPY TO SAME DEVICE AND DIRECTORY 
Explanation: You attempted to copy all versions of a efile 
into the same directory that is being scanned for input 
files. This would result in an infinite number of versions 


of the same file, so is not allowed. 


User Actions Reenter the command line, renaming the files 
OY COpyYlLng them 1nto a ariferent directory. 
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PIP -- ILLEGAL USE OF WILDCARD VERSION OR LATEST VERSION 


Explanation: The use of either a wildcard version number or 
a latest version number in the attempted operation would 
result in inconsistent or unpredictable output. 


User Actions: Reenter the command line with different 
options or with an explicit or default version number. 


PIP == INPUT FILES HAVE CONPLICTING ATTRIBUTES 


Explanation: The input files specified in a Merge, Update, 
or Supersede command had conflicting attributes or the 
attributes of the input file(s) specified in an Append 
command conflicted with those of the output file. 


User Action: The message is a warning only. The specified 
action was completed despite the conflict. With a Merge, 
Update, or Supersede command, the attributes of the output 
file will be those of the first input file. With an Append 
command, the attributes of the output file are unchanged. 
The resulting file should, however, be suspect because its 
attributes may not correctly represent ail the records in 


the file. 
PIP -- I/O ERROR ON INPUT FILE 
or 
PIP -- I/O ERROR ON OUTPUT FILE 


Explanation: One of the following conditions may exist: 
® The device is not on-line 

@® The device is not mounted 

@® The hardware has failed 

@ The volume is full (output only) 

@ The input file is corrupted 


Note that these are the most. common Conditions: Conditions 
other than those listed may have caused the message. 


User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 
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PIP -- NOT A DIRECTORY DEVICE 


Explanation: A directory-oriented command was issued to a 
device that does not have directories (such as a printer). 


User Actions Reenter the command line without specifying a 
directory. 
PIP -- NOT ENOUGH BUFFER SPACE AVAILABLE 


Explanations PIP did not have enough I/O buffer space to 
perform the requested command. 


User Actions You cannot use PIP to perform the requested 


operation. Submit a Software Performance Report to your 
local DIGITAL representative. 


PIP <= NO. SUCH FILE CS) 


Explanation: The file(s) specified in the command was(were) 
not found in the designated directory. 


User Action: Check the file specification and reenter’ the 
command line. 
PIP -- ONLY [*] IS LEGAL AS DESTINATION UIC 


Explanation: A directory other than [*] was specified as 
the output file directory for a copy operation. 


User Action: Reenter the command line with [*] specified as 
the output directory. 


PIP -- OPEN FAILURE ON INPUT FILE 
or 
PIP -- OPEN FAILURE ON OUTPUT FILE 
Explanation: The specified file could not be opened. One 


of the following conditions may exist: 


® The file is protected against access. 
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A problem on the physical device (for example, device 
down). 


@ The volume is not mounted. 

@ The specified file directory does not exist. 

® The named file does not exist in the specified 

directory. | 

Note that these are the most common conditions. Conditions 
other than those listed may have caused the message. 
User Action: Determine which condition caused the message 
and correct that condition. Reenter the command line. 


PIP -- OUTPUT FILE ALREADY EXISTS -- NOT SUPERSEDED 


Explanation: An output file of the same name, type, and 
version as the file specified already exists. 


User Action: Retry the copy with /NV to assign a new 
version number or use /SU to supersede the output file. 
PIP -- TOO MANY COMMAND SWITCHES - AMBIGUOUS 


Explanations Too many switches were specified or the 
Switches conflict. 


User Action: Reenter the command line, specifying the 
correct set of switches. 
PIP -- VERSION MUST BE EXPLICIT OR "*" 


Explanation: The version number of the specified file must 
be expressed explicitly or as a wildcard (*). 


User Action: Reenter the command line with the version 
number correctly expressed. 


12.7 PIP ERROR CODES 


Table 12-3 identifies error codes PIP issues when it cannot 
access the message file. The descriptions and suggested user 
actions are identical to those described in Section 12.6. 


be 


Table 12-3: 


Code 


CO OV On WN F 
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PIP Error Codes and Messages 


Message 


Command syntax error 

Invalid switch 

Too many command switches--ambiguous 

Only [*,*] is legal as destination UIC 
Invalid command 

Invalid "*" copy to same device and directory 
Bad use of wildcards/characters in destination filename 
Explicit output filename required 
Allocation failure--no contiguous space 
Allocation failure--no space available 
Allocation failure on output file 

1/O error on. input file 

1/O error on “output. file 

Invalid use of wildcard version or latest version 
Failed to create output directory 

Input files have conflicting attributes 
Open failure on input file 

Open failure on output file 

Close failure on input file 

Close failure on output file 

Failed to detach output device 

Device not mounted/allocated 

Output file already exists--not superseded 
Failed to mark file for delete 

File is lost 

Version must be explicit or "x" 

Error [rom parse 

Failed to delete file 

Failed to attach terminal 

Invalid response--try again 

Cannot exclude *.*;* 

Cannol. 21nd directory t2ie 

Failed to attach output device 

Failed to get time parameters 

Not a directory device 

Failed to write attributes 

Failed to read attributes 

File not locked 

Failed to enter new filename 

Failed to restore original directory entry--file lost 
Cannot rename from one device to another 
Failed to ‘spool file-tor printing 
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Message 


Cannot 
Failed 
Failed 
Failed 
Cannot 
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spool by file ID 

to open storage bitmap file 
to open index file 

to find file(s) 

find file(s) 


No such file(s) 


Failed 


to remove directory entry 


Directory write protected 
Not enough buffer space available 


Failed 
Cannot 


to truncate file 
truncate this filetype 


Invalid EOF value 
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OBJECT MODULE PATCH UTILITY (PAT) 


The Object Module Patch Utility (PAT) allows you to update, or 
patch, code in a relocatable binary object module. 


Input to PAT is two files, an input file and a correction file. 
The input file consists of one or more concatenated object 
modules. You can correct only one of these object modules with a 
Single execution of PAT. The correction file consists of object 
code that, when linked by the Task Builder, either overlays or is 
appended to the input object module. 


Unlike the Task Builder and ZAP patching options, PAT allows you 
to increase the size of the object module because the changes are 
applied before the module is linked by the Task Builder. 


PAT uses the correction file, which contains corrections and/or 
additional instructions, to update the object module. Correction 
input iS prepared in source form and then assembled by the 
MACRO-11 assembler. 


Output from PAT is the updated input file. 


Using PAT to update a file involves several steps. First, you 
create the correction file using a text editor. Once created, 
the correction file must be assembled to produce an object 
module. The correction file and the input file (both in object 
module format) are then submitted to PAT for processing. 


Finally, the updated input object module is submitted to the Task 
Builder to resolve global symbols and to create an executable 
task. Figure 13-1 shows the processing steps involved in 
generating an updated task file using PAT. 
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13.1 INVOKING PAT 
To invoke PAT, enter the following command: 
S RUN SPAT 
PAT can be used interactively or by means of indirect command 


Files. If you use indirect command files, PAT allows a maximum 
nesting level of 2. 


13.2 PAT COMMAND LINE FORMAT 

Specify the PAT command line in the following format: 
foutfile]=infile[/CS[:number]],correctfile[/cS: [number] ] 

outfile 


The file specification for the output file. If you do not 
specify an output file, PAT does not generate one. 


infile 


The file specification for the input file. This file can 
contain one or more concatenated object modules. 


correctfile 
The file specification for the correction file. This file 
contains the updates to be applied to one module in the 
input. Erie. 


/CS[enumber ] 


Specifies the Checksum switch. This switch directs PAT to 
calculate the checksum for all the binary data that 


constitutes the module. PAT displays this checksum in 
octal. (Refer to Section 13.3.4 for information on how to 
use /CS.) 

You can optionally specify an octal number with /CS. Then, 
after PAT calculates the checksum value, it compares that 
value with the number you specified. If the values are not 
the same, PAT informs you with an error message. You must 


then rerun PAT, specifying the correct checksum. 


te tee 


PAT COMMAND LINE FORMAT 


CORRECT SRC 


TEXT 1. Generate a correction file using ee 
EDITOR the Text Editor. 


CORRECT SRC CORRECT.OBJ 


2. Execute the assembler (or compiler) 
> to generate an object module a 
version of the file. 


CORRECT.OBJ 


MYFILE.OBJ 


3 Execute PAT using as input the 
correction file and the module to > 
be updated. 


MYFILE.OBJ 


MYFILE.OBJ MYFILE TSK 
4. Execute the Task Builder to 
TASK resolve new addresses and eee 
BUILDER generate an executable task 
ZK-199-81 


Figure 13-1: Using PAT 


13.3 HOW PAT APPLIES UPDATES 


This section describes the PAT input and correction files, gives 
information on how to create the correction file, and gives 
examples of how PAT applies the corrections to a module. 
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13.3.1 The Input File 


The input file is the file to be updated; it is the base for the 
SUEpUE: ti be:. The input file must be in object module format. 
When you execute PAT, the correction file is applied to one of 
the object modules in the file. PAT assumes a file type of .OBJ 
for. the anput. fice. Lf “you. vse a tide type other than: <OBJ, you 
must specify it explicitly in the command line. 


13.3.2 The Correction File 


The correction file contains the patches to be applied to the 
input file. PAT assumes a file type of .OBJ for the correction 
file. If you use a file type other than .OBJ, you must specify 
it explicitly in the command line. 


As shown in Figure 13-1, the first step in using PAT to update an 
object file is to generate the correction file. Use any text 
editor to create this source file, which is usually in _ the 


following format: 


.TITLE inputname 
.- IDENT updatenum 
inputline 
inputline 


inputname 


The name of the module to be corrected by the PAT update. 
You must specify the module that you are updating for 


inputname. 


updatenum 


Any value acceptable to the MACRO-11 .IDENT assembler 
directive. Generally, this value reflects the updated 
version of the file to be processed by PAT. 


NOTE 
The .IDENT assembler directive is a required part 
of the correction file. Failure to include an 
.IDENT directive in the file produces unusable 
output. 
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inputline 


Lines of input to be used to correct and update the input 
file. 


Once you have created the source version of the correction file, 
you assemble it to produce an object module that can be processed 
by PAT. 


During PAT execution, new global symbols defined in the 
correction file are added to the module’s symbol table. A symbol 
definition that is already being used in the input file can be 
superseded by the definition in the correction file. Fora 
symbol definition to be superseded, both definitions must _ be 
either relocatable or absolute. 


A duplicate program section supersedes the previous program 
section, provided: 


o Both have the same relocatability attribute (ABS or REL) 
o Both are defined with the same directive (.PSECT or .CSECT) 


If PAT encounters duplicate program section names, the length 
attribute for the program section is set to the length of the 
longer program section and a new program section is appended to 
the module. 


If you specify a transfer address, it supersedes the transfer 
address of the module being patched. 


13.3.3. How PAT and the Task Builder Update Object Modules 


The examples in the following sections show an input file and a 
correction file (both in object module format) to be processed by 
PAT and the Task Builder, along with a source-like representation 
of how the output file looks once PAT and the Task Builder 
complete processing. Two techniques are described: one for 
overlaying lines in a module, and the other for adding a 
subroutine to a module. 


13.3.3.1 Overlaying Lines in a Module - The Following 
example illustrates a technique using a patch file to overlay 
lines in a module. First, PAT appends the correction file to the 
Miput. “Lile. Then, the Task Builder generates a task image from 
the patched object modules. 
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The input file for this example is: 


TITLE: ABC 
.IDENT /01/ 


ABG 3: 
MOV A,C 
CALL XYZ 
RETURN 
- END 


To add the instruction ADD A,B after the CALL instruction, you 
can use the following patch in the correction file: 


SEET GE “ABC 

eDDEN? 701.017 
=.+12 

ADD A,B 

RETURN 

- END 


You use the MACRO-11 assembler to assemble the correction file. 
After assembly, PAT processes the resulting object module and the 
input object module. The result of PAT processing appears as 
follows: 


.TITLE ABC 
.IDENT /01.01/ 


ABC:: 

MOV A,C 
CALL XYZ 
RETURN 

=ABC 

= .+12 
ADD A,B 
RETURN 
. END 


You then use the Task Builder to produce the patched object 
module as a task image. This task image looks the same as the 
source code would have looked if it had originally been written 
as follows: 


SILTGE: ABC 
-LDENE 01.077 


ABC?:: 
MOV Pig 
CALL XYZ 
ADD A,B 
RETURN 
. END 
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PAT uses the .=.+12 in the program counter field to determine 
where to begin overlaying instructions in the program. It 
overlays the RETURN instruction with the patch code: 


ADD A,B 
RETURN 


13.3.3.2 Adding a Subroutine to a Module - The second 
example illustrates a technique for adding a subroutine to an 
object module. A patch often requires that more than a few lines 
be added to correct the file. A convenient technique for adding 
new code is to append it to the end of the module as a 
subroutine. That way, you insert a CALL instruction at an 
appropriate location in the subroutine. The CALL instruction 
directs the program to branch to the new code, execute that code, 
and then return to in-line processing. 


The input file for this example is: 


STLTLE. ABC..~ 
IDENT /01/ 


ABC:: 
MOV A,B 
CALL XYZ 
MOV C,RO 
RETURN 
. END 


The correction file for this example is: 


STITLE ABC 
-IDENT. 701017 


CALL PATCH 

NOP 

sPOoECr PATCH 
PATCH $ 

MOV A,B 

MOV D,RO 

ASL RQ 

RETURN 

. END 
PAT merges the correction file with the input file, as in the 
first example. The Task Builder then processes the files and 


produces a task image that looks the same as the source file 
would have looked if it had originally been written as follows: 
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.TITLE ABC 
.IDENT /01.01/ 


ABCs: 
CALL PATCH 
NOP 
CALL XYZ 
MOV C,ROQ 
RETURN 
-PSECT PATCH 
PATCH: 
MOV A,B 
MOV D,RO 
ASL RQ 
RETURN 
- END 


In this example, the CALL PATCH and NOP instructions overlay the 
3-word MOV A,B instruction. (The NOP is included because this is 
a case where a 2-word instruction replaces a 3-word instruction 
and NOP is required to maintain alignment.) The Task Builder 
allocates additional storage for  .PSECT PATCH, writes the 
specified code into this program section, and binds the CALL 
instruction to the first address in this section. The MOV A,B 
instruction, replaced by the CALL PATCH instruction, is the first 
instruction executed by the PATCH subroutine. 


13.3.4 Determining and Validating the Contents of a File 


You use the Checksum switch (/CS) to determine or validate the 
contents of a module. The switch directs PAT to calculate the 
checksum (in octal) for all the binary data that constitutes’ the 
module and to then inform you of the checksum by means of a 
diagnostic message. 


To determine the checksum of a file, enter the PAT command line 
with the /CS switch applied to that file’s specification. For 
example: 


=MYFILE/ CS, CORRECT. POR 


The command directs PAT to calculate the checksum for the input 
file, MYFILE.PAT then responds with the message: 


INPUT MODULE CHECKSUM IS checksum 
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PAT generates a Similar message when you request the checksum for 
the correction file. For example: 


=MYFILE,CORRECT.POB/CS 


After calculating the checksum for the correction file, PAT 
responds with the message: 


CORRECTION INPUT FILE CHECKSUM IS checksum 
If you specify /CS:number to validate the size of a file, PAT 
calculates the checksum for the file and then compares that 
checksum with the value you specified as number. If the two 
values do not match, PAT displays the following message to report 
the checksum error: 

ERROR IN FILE filename CHECKSUM 
For example, you might specify: 


=MYFILE, CORRECT. POB/CS: 432163 


When PAT calculates the checksum for the correction file, the 
number is different. PAT then displays the message: 


ERROR IN FILE CORRECT.POB CHECKSUM 


Checksum processing always results in an octal, nonzero value. 


13.4 PAT MESSAGES 

PAT generates messages that state checksum values and messages 
that describe error conditions. For checksum values and nonfatal 
error messages, PAT prefixes the messages with: 


PAT -- *DIAG*-error message 


For messages that describe fatal errors (errors that caused PAT 
to terminate), PAT uses the prefix: 


PAT -- *FATAL*-error message 
The following messages are grouped according to message type, as 
follows: 


® Information messages 
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@® Command line errors 

@ File specification errors 

@ JInpurvoutpur errors 

® File content or format errors 
® Internal software error 


e Storage allocation error 


13.4.1. Information Messages 
The following messages describe results of checksum processing. 
CORRECTION INPUT FILE CHECKSUM IS checksum 
Explanation: When you specify /CS in the correction file 
specification, PAT informs you of the file’s checksum value. 


The value is given in octal. 


User Actions No response necessary. 


INPUT MODULE CHECKSUM IS checksum 
Explanation: When you specify /CS in the input file 
specification, PAT informs you of the file’s checksum value. 


The value is given in octal. 


User Action: No response necessary. 


13.4.2 Command Line Errors 

The following error messages result from failure to adhere to the 
command line syntax rules. 

COMMAND LINE ERROR command line 


Explanation: The system standard command line processor 
(.GCML) detected an error in the command line. 
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User Actions Reenter the command line using the correct 
information. 

COMMAND SYNTAX ERROR command line 
Explanation: The command line contained a syntax error. 
User Action: Reenter the command line using the correct 
syntax. 

ILLEGAL INDIRECT FILE SPECIFICATION command line 


Explanation: You specified an indirect command file that 
contains one of the following errors: 


® A syntax error 
® A specification for a nonexistent indirect command file 
User Actions Check for file specification syntax errors or 
ensure that the specified file is contained in the specified 
User File Directory. Reenter the command line. 

MAXIMUM INDIRECT FILE DEPTH EXCEEDED command line 
Explanation: In the command line, you specified an indirect 
command file that exceeds the maximum nesting level of 2 


that is permitted by PAT. 


User Action: Reorder your files so that they do not’ exceed 
PAT’s nesting limit. 


13.4.3 File Specification Errors 


The following error messages are caused by errors in _ the 
epecification of: input of 6utpul files.or related file switches. 


CORRECTION INPUT FILE MISSING command line 


Explanation: The mandatory COrrectron file was HOt 
specified. 
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User Actions Reenter the command line specifying the 
correctiom £1le. 


ILLEGAL DEVICE/VOLUME SPECIFIED device name 


Explanation: The device or volume name specification 
contained a syntax error. 


User Actions Check the rules for specifying devices and 


volumes, then reenter the command line using the correct 
syntax for the device or volume specification. 


ILLEGAL DIRECTORY SPECIFICATION directory name 


Explanation: The directory specification contained a syntax 
error. 


User Actions Check the rules for specifying a directory and 
reenter the command line using the correct syntax for the 
directory specification. 

ILLEGAL FILE SPECIFICATION filename 


Explanation: The file specification contained a syntax 
error. 


User Actions Reenter the command line using the correct 
syntax for the file specification. 


ILLEGAL SWITCH SPECIFIED filename 


Explanation: An unrecognized switch or switch value was 
specified with the file. 


User Actions Check the rules for specifying the switch and 
reenter the command line using the correct switch or switch 


value. 
INVALID FILE SPECIFIED filename 


Explanation: You specified a file that contains one of the 
following errors: 


® Nonexistent device 
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® Nonexistent directory - The directory in the filename 
Specification does not exist on the specified device (or 
on the default device if no device was specified). 
User Actions Reenter the command line specifying the 
correct. device or directory. 


MULTIPLE OUTPUT FILES SPECIFIED command line 


Explanation: PAT accepts only one eucout file 
specification. 


User Actions Reenter the command line specifying only one 
outpuc. tite 
REQUIRED INPUT FILE MISSING command line 


Explanation: The mandatory input file was not specified in 
the command line. 


User Actions Reenter the command line specifying an input 
File. 

TOO MANY INPUT FILES SPECIFIED command line 
Explanation: Too many input files were specified in the 
command line. PAT accepts only the input and correction 
file specifications. 
User Action: Reenter the command line specifying the 
correct files. - 


UNABLE TO FIND FILE filename 


Explanation: PAT could not locate the specified input’ or 
correction file. 


User Action: Check the directory to ensure that the file 


exists. Reenter the command line specifying the correct 
filename. 


13.4.4 Input/Output Errors 


The following error messages are caused by faults detected while 
PAT was performing I/O to the specified file. 
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ERROR DURING CLOSE: PILE: filename 
Explanation: This error is most likely to occur while PAT 
1S attempting to write the remaining data into the output 


file before deaccessing it. The most likely causes of this 
error are the following conditions: 


e The device is full 

@® The device is write-locked 

@® A hardware error occurred 

User Actions Perform the appropriate corrective action and 
reenter the command line: if the device is full, delete all 
unnecessary files; iE the device is write-locked, 


write-enable it; if the problem is a hardware error, contact 
your DIGITAL Field Service representative. 


ERROR POSITIONING FILE filename 


Explanation: PAT attempted to position the file beyond 
end-of-file. 


User Action: Submit a Software Performance Report along 
with the related console dialog and any other pertinent 
information. 


T/O ERROR ON INPUT FILE filename 
Explanation: An error was detected while PAT was attempting 
to read the specified input file. The principal cause of 


this error is a device hardware error. 


User Action: Reenter the command. 


170: ERROR ON OUTPUT FILE E£1lename 
Explanation: An error occurred while PAT attempted to write 
into the named output file. The most likely causes of this 


error are the following conditions: 


@® The device is full 


13-14 


PAT MESSAGES 


® The device is write-locked 
@ A device hardware error occurred 


User Actions Perform the appropriate corrective action and 
reenter the command line: if the device is full, delete all 
unnecessary files; Ve the device is write-locked, 
write-enable it; if the problem is a hardware error, contact 
your DIGITAL Field Service representative. 


13.4.5 Errors in File Contents or Format 


The foilowing errors represent inconsistencies detected by PAT in 
the format or contents of the input or correction files. 


ERROR IN FILE filename CHECKSUM 


sha ey 


Explanation: The checksum that PAT calculated for the named 
file does not match the one that you specified with 
J/CS<number:. 


User Actions Ensure that you specified the correct 
checksum. If the checksum is correct, then you specified an 
invalid version of the file. Rerun PAT specifying the 


correct version of the file. 


filename HAS ILLEGAL FORMAT 

Explanation: The format of the named file is not compatible 
with the object files produced by the standard DIGITAL 
language processors or accepted by the Task Builder. The 
principal causes are: 

@® Truncated input file 


® Input file that consists of text 


User Action: Ensure that the file is in the correct format 
and resubmit it for PAT processing. 
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INCOMPATIBLE REFERENCE TO GLOBAL SYMBOL symbol name 
Explanation: The correction file contains a global symbol 
whose attributes do not match one or more of the following 
input file symbol attributes: 
® Definition or reference 
@® Relocatable or absolute 
User Actions: Update the correction file by modifying the 
symbol attributes. Reassemble the file and resubmit it for 
PAT processing. 

INCOMPATIBLE REFERENCE TO PROGRAM SECTION section name 
Explanation: The correction file contains a section name 
whose attributes do not match one or both of the following 
input file section attributes: | 
e Relocatable or absolute 
® Defined with the same directive (.PSECT or .CSECT) 

User Action: Update the correction file by modifying the 
section attribute or changing the section type. Reassemble 
the file and resubmit it to PAT for processing. 


UNABLE TO LOCATE MODULE module name 


Explanation: PAT could not find the module name that was 
specified in the correction file in the file of concatenated 
input modules. 


User Action: Update the input file specification to include 
the missing module. Reenter the command line. 


13.4.6 Internal Software Error 
This error reflects internal software error conditions. 
ILLEGAL ERROR-SEVERITY CODE error data 


Explanations An error message call, containing an illegal 
parameter, has been generated. 
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User Action: If these messages persist, submit a Software 
Performance Report along with related console dialog and any 
other pertinent information. 


13.4.7 Storage Allocation Error 


The following error message indicates that not enough task memory 
was available for storing global symbol and program section data. 


NO DYNAMIC STORAGE AVAILABLE storage-listhead 


Explanation: Not enough contiguous task memory was 
available to satisfy a request for the allocation of 
storage. 


PAT displays the contents of the 2-word dynamic’ storage 
listhead in octal. 


User Action: You cannot use PAT to correct the input file. 


UNABLE TO OPEN FILE filename 


Explanation: There is insufficient work space in the 
internal File Storage Region (FSR) of the PAT Utility. 


User Action: You cannot use PAT to correct the input file. 
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CHAPTER 14 
FILE STRUCTURE VERIFICATION UTILITY (VFY) 


The File Structure Verification Utility (VFY) for FILES-11 
volumes provides the ability to: 


@® Check the readability and validity of a file-structured 
volume (default function). 


® Print the number of available blocks on ae file-structured 
volume (/FR). 


@ Search for files in the index file that are not in any 
directory; that is, files that are "lost" in the sense that 
they cannot be accessed by filename (/LO). 

@ Validate directories against the files they list (/DV). 


e List all files in the index file, showing the file ID, 
filename, and owner (/LI). 


@ Perform a read check on every allocated block on ae file- 
structured volume (/RC). 


The volume to be verified must be mounted as a FILES-11 device. 
There should be no other activity on the volume while VFY is 
executing. In particular, activities that create new files, 


extend existing files, or delete files should not be attempted 
while VFY is executing a function. 


14.1. INVOKING VFY 


To invoke VFY type: 


S RUN SVFY 
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VEY will prompt: 


VEY> 


14.2 VFY COMMAND FORMAT 

The command line for VFY uses the format: 
VFY>listfile,scratchdev=indev/switch 

The parameters of this command format are: 

Output Parameters 

listfile 
Specifies the output listing file in the following format: 

dey e[(utd Er lename.tiletype; ver 


If you do not specify a device, the default for the output 


listing device is the issuing terminal (TI:). The [ufd] is 
the UIC under which VFY is currently running. You must, 
however, specify the filename and file type of the output 
file. The default version number will be the latest version 
plus one. 

scratchdev 


Specifies the device on which the scratch file produced by 
VFY is to be written. This parameter is in the following 
Lrormat: 


dev: 


The scratch file is used by VFY during the verification scan 


and during the lost file scan. It is created but not 
entered in a directory. Therefore, it is transparent to 
you. The scratch file is automatically deleted when VFY is 
terminated. If you do not specify a scratch device the 


default device is SYO:. 


If the user’s default system disk is faulty or full, use 
this parameter to direct the scratch file to another device. 
The scratch file should always be assigned to a volume other 
than the indev volume. The scratch file is not used with 
tne /FR and /LI switches. 


Input Parameters 
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indev 


Specifies the volume to be verified in the format dev:. If 
you do not specify the volume, the default is SY0O:. 


/switch 


Specifies the function to be performed by VFY. 


14.3 VFY MODE OF OPERATION 


VFY normally operates in read-only mode, where the scratch file, 
if required, 1S on another device. 


If the /LO switch is specified and lost files are found, VFY 


requires write: access. to’ [1,3]% waich 1s: the directory containing 
lost files. 


14.4 VFY VALIDITY CHECK 
VFY checks the readability and validity of the volume mounted on 
the specified device. This function is the default function and 
entails reading all the file headers in the index file and 
ensuring that all the disk blocks referenced in the map area of 
each file header are allocated to that file in the volume bitmap. 
The volume may be write-protected if it is not the system volume, 
or if the required scratch file is directed to another file- 
structured volume. 
A validity check is specified in the following format: 

listfile,scratchdev=indev<RET> 

or 
indev<RET> 


Example 


S RUN SVFY 
VFY>DRO: 


CONSISTENCY CHECK OF INDEX AND BITMAP ON DRO: 
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INDEX INDICATES 114524. BLOCKS FREE, 17156. BLOCKS USED OUT OF 131680. 
BITMAP INDICATES 114524, BLOCKS PREE, 17156. BLOCKS USED -OUT “OF 131680. 


14.5 VFY SWITCHES 
VFY functions are specified with switches appended to the VFY 


command line. The switches and their functions are summarized in 
Table 14-1. 


Table 14-1: VFY Switches and Functions 


Switch Format Description 


Directory Validation /DV Validates directories against 
the files they list. 


Free JER Prints out the available space 
on a volume. 


Identify res. Identifies the VFY version. 
This switch may be specified on 
a command line by itself at any 


time. 

List foe Lists the index file by file 
ED 

Lost /LO Scans the file structure 


looking for files which are not 
im: any directory. 


Read Check — /RC Checks the volume to see if 
every block of every file can 
be read. 


14.5.1 Directory Validation Switch (/DV) 


The Directory Validation Switch (/DV) examines each directory on 
the volume. (VFY considers any file on the volume with the file 
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type .DIR and a fixed record length of 16 bytes to be a 
directory.) It then reports any errors found that could be 
attributed to a corrupt directory or a nonexistent file listed in 
the directory. For example: 


S RUN SVFY 

VEY>DX: /DV 

THE FOLLOWING DIRECTORY ENTRIES WERE INVALID 

[301,333] FILE ID 13,2,0 DELETED.FIL;1 - FILE NOT FOUND 

[301,333] FILE ID 12345,3,0 CORRUPTED.FID;1 - FILE NOT FOUND 

[301,333] FILE ID 14,2,0 GARBAGE.VER;123456 - INVALID VERSION NUMBER 
[301,333] FILE ID 15,1,444 RELVOLNEZ.ERO;1 - RESERVED FIELD WAS NON-ZERO 


4. INVALID DIRECTORY ENTRIES WERE FOUND 
Directory entries may be invalid due to the following conditions: 
FILE NOT FOUND 
The file was either deleted without the corresponding 
directory entry being removed or the file ID field in the 
directory entry was corrupted. If the file does exist, it 
cannot be accessed with this directory entry. 
Remove the directory entry using the PIP /RM command. 


INVALID VERSION NUMBER 


The directory entry was corrupted. If the file does exist, 
it cannot be accessed with this directory entry. 


Remove version zero of the file with the PIP /RM command. 
RESERVED FIELD WAS NON-ZERO 

The third word of the file ID field in a directory entry 1s 

a reserved field and should always be zero. Remove the 


directory entry with PIP /RM and then reenter it with the 
PIP /EN command. 


14.5.2 Free Switch (/FR) 


The Free switch (/FR) displays the available space on a specified 
volume with the following message: 


dev: HAS nnnn. BLOCKS FREE, nnnn. BLOCKS USED OUT OF nnnn. 
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The List switch 


(/LT) 
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lists the index file. 


The output for each file specifies the file number, 
in the following 


number, 
example: 


filename, 


and o 


VPY>SDKi7 LI 
LISTING OF INDEX ON DKQ: 


PIGE 
FILE 
FILE 
FILE 
PLE 
PLE 
FILE 
FILE 
FLUE 
ELLE 
FILE 
PILE 


LD 
ID 
ID 
ID 
By B 
LD 
ID 
ID 
ID 
ID 
ID 
ID 


000001,000001 
000002,000002 
000003,000003 
000004,000004 
000005,000005 
000006,000006 
000007,000007 
000010,000010 
OU00LT, 0000 LL 
000012,000012 
000013,000036 
000014,000037 


14.5.4 Lost Switch (/LO) 


The Lost switch (/LO) 

that are not in any directory and 
Filename. (VFY considers any file 
filetype .DIR and ae fixed record 


directory.) 
file 


directory” 


[1,3] 


entered in that directory. 


directory 
deg Sells 


FALGED. TO OPEN. DIRECTORY .F UGE 
ERROR -CODE. =16:. 
AS A RESULT, 


file 


operation, 
The following error message will appear: 


wner 


INDEXF. 
BITMAP. 
BADBLK. 
so Re 


000000 


CORIMG. 
2D Rak 
sDIER s. 


001.007. 
001002 


ULC, 


SYor. 
SY¥S-2 1 
SYoe lL 


Soe 


EXEMC .MLB;1 


RSXMAC. 


SM: 21 


NODES.TBL;i 


OLOSiIM.MSG7 511 
F4PCOM. 


the 


= DIRECTORY 
NO FILES WILL BE ENTERED IN 


14.5.5 Read Check Switch (/RC) 


The Read Check switch 


(/RC) 


MSG;1 


A list of the files is produced, 
exists on that volume, 
it san. L/O error occurs, 


files will not be entered into 


as 


shown 


OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 
OWNER 


cannot 


the 


pou tg 3 35 


every file on a specified volume can be read. 
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PRPRPPPPPPPPP PB 


= = = = = ™ = = = “= = = 


NNPP PNP PRP RPP 


scans the file structure looking for 


file sequence 


files 


be referenced by 


[1,3] 


volume 
length of 16 bytes to be a 
and 
the files will be 


1 


checks to ensure that every block 


with Ene 


£f the "lost 


however, on a 


OF 


VFY SWITCHES 


The optional parameter [:n] is the blocking factor that indicates 
the number of file blocks to be read at a time. The default 
value is the maximum number of blocks available in VFY’s buffer 
area. The buffer area available may be increased by installing 
VFY in a larger partition. Four blocks are available when VFY is 
installed in an 8K partition, and four blocks are added for each 
1K increment. 


For the fastest read check, the maximum block factor should be 
used. Whenever an error is encountered, each block of the 
portion in error 1s reread to determine which data block(s) 
Cannot be read. 


When an error is detected, a file identification line is 
displayed in the following format: 


FILE ID nn,nn filename.typ;ver. on blocks used/n blocks allocated 


Following this line, an error message is displayed. If a 
blocking factor other than 1 is in use, an error message in the 
following form will be issued: 


ERROR STARTING AT VBN ni,n2 LBN n1,n2 - ERROR CODE -n 


Following the first error message, there should be one or more 
error mesSages indicating the exact block(s) in error. The 
second error message line(s) will be in the following form: 


ERROR AT VBN ni1,n2 LBN n1,n2 - ERROR CODE -n 


If an ERROR STARTING AT line is displayed without one or more 
ERROR AT lines, a multiblock read operation on the selected 
device has failed, but the data blocks appear to be individually 
readable. 


tf the VBN of the unreadable block listed in the ERROR AT line is 
beyond the block-used-count, the data portion of the file is 
readable. 


The negative number printed after the ERROR CODE message is 
usually -4 to indicate a device parity error. 


14.6 FILE ERROR REPORTING 


As VFY verifies a volume, error conditions are reported. Errors 
for a given file are preceded by a line that identifies the file 
in error. This line is formatted as follows: 


FILE ID nn,mm filename.filetype;version OWNER [uic] 
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nn,mm 


Represents the unique file identification number assigned to 
the file by the system at file-creation time. 


filename 
Represents the filename. 
filetype 


Represents the file type (for example, .OBJ for object 
File). 


sversion 

Represents the version number of the file. 
oegom 

Represents the UIC for the file. 


This file identification line is followed by one or more of the 
following messages: 


I/O ERROR READING FILE HEADER-ERROR CODE -32 
Explanation: VFY failed to read the file header for the 


specified file ID. The device iS not mounted or is 
off-line, or the hardware has failed. 


BAD FILE HEADER 


Explanation: VFY checks on the validity of the file header 
indicate that the header has been corrupted. 


MULTIPLE ALLOCATION n,m 


Explanation: The specified (double-precision) logical block 
number is allocated to more than one file. If this error 
occurs, a second pass automatically occurs that indicates 
all files that share each multiple-allocated block. The 
second pass is taken after all file headers are checked. 


BLOCK IS MARKED FREE n,m 
Explanations: The specified logical block number 1s 


allocated to the indicated file but is not marked as 
allocated in the storage allocation map. 
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BAD BLOCK NUMBER n,m 
Explanation: The specified block number was found in the 
header for this file but is illegal for the device (out of 
range). This indicates a corrupted file header. 

FILE IS MARKED FOR DELETE 
Explanations A system failure occurred while the specified 
file was being deleted. The deletion was not completed and 
the file header still exists. 

HEADER MAP ERROR 
Explanations VFY detected an error in the header map area 
that also indicates a corrupted file header. 

The last error message for the file is followed by a summary line 


for that file, as follows: 


SUMMARY: MULT=nn, FREE=nn, BAD=nn. 


MULT 
Specifies the number of multiple block allocations. 

FREE 
Specifies the number of blocks marked free that should have 
been allocated. 

BAD 


Specifies the number of errors encountered in the the map 
area of the file header. 


If the output for VFY is directed to a terminal and you do _ not 
wish to see the error messages for a given file, enter CTRL/O. 
This terminates the listing of error messages for that file that 
is, all messages but the summary line. 


14.6.1 Files Marked for Delete 


If a file has been marked for delete but the deletion process was 
not completed, you can either restore the file, if you still need 
it, or you can delete the file to recover the space it was 
occupying. This situation only occurs when the system crashes 
during file processing. 3 
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14.6.1.1 Deleting a File Marked for Delete - Files that 
are marked for delete can be deleted directly with PIP, once 
their unique file ID has been obtained by doing a validity check. 
The file ID appears as the first entry in the file identification 
line that precedes each list of file errors. The following 
example shows how the file ID is used with PIP to delete a file: 


S$ RUN SPIP 
PIP>/FI:12:20/DE 


In this example, the file with file ID 12,20 is deleted from the 
system device. PIP issues the error message: 


PIP ~- FAILED TO MARK FILE FOR DELETE-NO SUCH FILE 


since the file system denies the existence of files already 
marked for delete; however, the file is deleted. 


14.6.2 Deletion of Multiple-Allocated Blocks 


Tf the file structure contains multiple-allocated blocks, it is 
necessary to delete files until there are no such blocks. An 
automatic rescan of the volume identifies which files share which 
blocks. This rescan lists the files which contain the 
multiple-allocated blocks. Use this information to determine 
which, if any, of the files can be saved and then delete the rest 
with the PIP delete function. 


After the files have been deleted, VFY should be run once = again 
to ensure that all of the files containing multiple-allocated 
blocks have been deleted. 


14.6.3 Recovering Lost Blocks 


To determine whether any blocks have been lost on aéeéfile- 
structured volume, examine the last two lines of output from the 
Validity Check. The last two lines of output give the free space 


on the volume. The first line reports the amount of available 
Space according to the index file (that is, the number of blocks 
that are not in use by any file in the index file). The second 


line reports the amount of available space according to the 
storage allocation bitmap. 


If there are no errors, the two figures should agree. If the 
index file indicates that more blocks are free than the storage 
allocation bitmap indicate, then those blocks are "lost" (they 
appear to be allocated, but no file contains them). 
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14.7 VFY ERROR MESSAGES 


The VFY error messages, their explanations, and suggested user 
actions are described below. 


VFY -- COMMAND SYNTAX ERROR 


Explanation: The command as entered does not conform to 
command syntax rules. 


User Actions Reenter the command line with the correct 
syntax specified. | 


VFY -- CLOSE FAILURE ON BIT MAP 
or 

VFY. ==. CLOSE FAILURE ‘ON INDEX FILE 
or 

VFY == CLOSE. FATLURE: ON TEMPORARY FILE 
or 

VFY -- CLOSE FAILURE ON LISTING FILE 
Or 

VFY -- I/O ERROR ON INPUT FILE 
or 

VEY == 170 ERROR ON. OQUTPUP FILE 
or 

VFY -- I/O ERROR READING DIRECTORY FILE 
or 

VFY -- I/O ERROR WRITING FILE HEADER 
or 
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VEY ~s= PAITLED TO “CLOSE: DIRECTORY. FLEE 
Explanation: One of the following conditions may exist: 
@ The device is not on-line 
@ The device is not mounted 
@ The hardware has failed 
User Actions Determine which of the above conditions caused 
the message and correct that condition. Reenter the command 
line. 
VFY j-- FAILED TO ALLOCATE SPACE FOR TEMP FILE 


Explanations The volume specified for the temporary scratch 
file ws full. 


User Action: Use PIP to delete unnecessary files and rerun 


VFY, or specify another volume as the scratch device when 
you reenter the command line. 


VFY -- FAILED TO ATTACH DEVICE 


VFY -- FAILED TO DETACH DEVICE 


Explanation: The list file specified a terminal device. 
VFY was not able to attach or detach the device. 


User Action: Reenter the command line with a list file 
device that can be attached or detached. 


VFY -- FAILED TO ENTER FILE 
Explanation: One of the following conditions may exist: 
® VFY is not running under a system UIC 
® The device is not on-line. 
© The device is not mounted. 


® The hardware has failed. 
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User Actions Determine which of the conditions caused the 


message and correct that condition. Reenter the command 
line. 

VFY -- FAILED TO FIND INDEXF.SYS;1 IN MFD-WILL OPEN INDEX BY FILE ID 1,1 
or 

VFY -- FAILED TO FIND BITMAP.SYS;1 IN MFD-WILL OPEN BITMAP BY FILE ID 2.2 


Explanations: The Master File Directory has been corrupted. 


User Actions Copy the disk using the BRU Utility. 


VEY == (FPAILED: TO OPEN: DIRECTORY PELE (See “OPEN FALLURE -error 
messages) 
VEY == ILLEGAL DEVICE 


Explanation: The input device specified is something other 
than a disk or DECtape. 


User Action: Reenter the command line with a mounted 
FILES-11 device specified. 


VFY -- ILLEGAL SWITCH 


Explanations The switch specified is not a valid VFY switch 
or a valid switch is used illegally. 


User Action: Reenter the command line with the correct 
Switch specified. 


VFY -- NO DYNAMIC MEMORY AVAILABLE - PARTITION TOO SMALL 
Explanation: VFY does not have enough buffer space to run. 


User Action: Run VFY in a larger partition (8K minimum). 


VFY -- OPEN FAILURE ON BIT MAP 
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VFY 


VEY 


VEY 
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or 
- OPEN FAILURE ON INDEX FILE 

or 

- OPEN FAILURE ON LISTING FILE 

or 

- OPEN FAILURE ON TEMPORARY FILE 

or 

== .PAILED TO OPEN DIRECTORY FILE 

or 

-- FAILED TO OPEN FILE FOR READ CHECK 

Explanation: One of the following conditions may exist: 
@ VFY 1S not running under a system UIC but should be. 


e The named file does not exist in the specified 
directory. 


8 The volume is not mounted. 
S The specified file is read protected. 
@ The specified file does not exist. 


User Actions: Determine which of the above conditions caused 
the message and correct that condition. Reenter the command 
line. 


-- STORAGE CONTROL BLOCK (VBN1 of BITMAP.SYS) IS CORRUPTED 


Explanation: The Storage Control Block is corrupt. This is 
harmless, because only VFY and PIP /FR can examine the 


BLOCK: 


User Action: Copy the disk using the Backup and Restore 
Util cy. 
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-- THEY ARE STILL LOST, COULD NOT FIND DIRECTORY 
Explanation: UFD [1,3] did not exist on the volume. UFD 
[1,3] is the "lost files" directory. VFY enters all files 
found by the /LO switch into this directory. 


User Action: Use the DCL CREATE/DIRECTORY command to enter 
UFD [1,3] on the volume. 3 
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Most DCL commands initiate functions that are actually performed 


by some other system task or utility. Table A-1 lists these 
relationships. 


Table A-1: Functions Initiated by DCL Commands 


DCL Task/Utility Installed 
Command Filename Task Name 
ABORT LB: [ZZPRODCL |CATCH.TSK ers OF 2: 
APPEND LB:[ZZPRODCL|PIP.TSK ee ol be og 
ASSIGN LB S| ZAPRODCE | LCT.ToR ak 
ASSIGN/TASK LB: ([(ZZPRODCL]CA2.TSK wig oe 
BASIC (Language dependent) nace eZ 
CANCEL LB? { 2ZPRODCE LCT. TSK ...- MMV 
COBOL (Language dependent) saeco 
CONTINUE LBs Z2Z4PRODCL |} LCE. TOR «2. MMV 
CONVERT LB: [{ZZPRODCL ]RMSCNV.TSK Sa tONV 
COPY LB: [| ZZPRODCL | PEP.TSK eee a Ow 
CREATE LB: [ZZPRODCL]PIP.TSK arg ode 
CREATE/DIR LB: [ZZPRODCL]LCT.TSK ...MMV 


FUNCTIONS INITIATED BY DCL COMMANDS 


DCL 
Command 


DEASSIGN 
DEFINE 
DELETE 
DIBOL 
DIFFERENCES 


DIRECTORY 
(Local files) 


DIRECTORY 
(Remote files) 


DIRECTORY/ATTRIBUTES 
DISMOUNT 

DUMP 

EDIT/EDT 

EDIT/SLP 


EDIT/PROSE 
(Starts the editor) 


EDIT/PROSE 
(PROSE editor) 


FORMAT 
FORTRAN 
HELP 
INITIALIZE 
INSTALL 
LIBRARY 


LINK 


Task/Utility 
Filename 


LB: [ZZPRODCL]LCT.TSK 
LB: [ZZPRODCL]LCT.TSK 
EB: Z2ZPRODChD)} PIP <TSk 
(Language dependent) 
LBs ZA2PRODCL CMP. TSK 


LB: [ZZPRODCL]PIP.TSK 


LB: [ZZDECNET |NFT.TSK 


LB:[ZZPRODCL]RMSDSP.TSK 


LB: [ZZPRODCL]LCT.TSK 
LB: [ZZPRODCL]DMP.TSK 
LB: [ZZPRODCL]EDT.TSK 


LB: [ZZPRODCL]SLP.TSK 


LB: [ZZPRODCL ] DCLPROSE.TSK 


LB: [ZZSYS]CET.TSK 


LB: [ZZPRODCL]LCT.TSK 


(Language dependent) 


LB:[ZZPRODCL]HELP.TSK 


LB: [ZZPRODCL]LCT.TSK 
LB: {ZZPRODCL|LCT.TSK 
LB: [ZZPRODCL]LBR.TSK 


LB: [ZZPRODCL]PAB.TSK 


Installed 
Task Name 


- MMV 


«os MMV 


NET 


sDSP 


- MMV 


«DMP 


2&DT 


wo LP 


»PRO 


6s 


. MMV 


i an ae | 


DCL 
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Command 


LINK 
(Inv 
.P 
LOAD 
MACR 


MOUN 


/C8B1 
OKC S> 4.2, BED, 


AB, and ...PIP) 


0 


T 


PASCAL 


PURG 


E 


REMOVE 


RENAME 


RUN 
CLE 
inst 
runs 
SET 
SET 
SET 
SET 
SET 


SEL 


SHOW 


the task is 
alled, DCL 
the task.) 
[DAY ]TIME 
DEFAULT 
DEVICE 
PRIORITY 
PROTECTION 


TERMINAL 


ASSIGNMENTS 


(Show a specific 


LOGa 


SHOW 


(Show all logicals) 


SHOW CLOCK QUEUE 


SHOW 


SHOW 


cal) 


ASSIGNMENTS 


COMMON 


[DAY ]TIME 


Task/Utility 
Filename 


(Language dependent) 


LB: [ZZPRODCL]LCT.TSK 


LB: [ZZPRODCL]PMA.TSK 


DBs 2ZERORCE LUCE eTSk 


(Language dependent) 


LB 


LB 


LB 


GB: 


LB 


bp 


| 


L's 


6: 


LB: 


1 a 


ep ss 


iB 


LBs 


LB: 


:[ZZPRODCL]PIP 
: [ ZZPRODCL]LCT 
: [ZZPRODCL]PIP 


[ZZPRODCL]LCT 


[ZZPRODCL ]CA2 


[ ZZPRODCL]CA2 
[ ZZPRODCL]CA2 
[ZZPRODCL]PIP 
[ZZPRODCL]CA2 


[A2ZPRODCE| LCT 


[ZZPRODCL]CA2 


[ZZPRODCL]CA2 


[ZZPRODCL]LCT. 


[ZZPRODCL]CA2. 


7loK 


2K 


tok 


Pap Res os 


, Lok 


oR 


stoK 
sok 
sok 
syd 


71 SK 


[ZZPRODCL]LNBDMP.TSK 


ok 


o Cok 


Tok 


Installed 
Task Name 


JoGD 


. MMV 


. PMA 


. MMV 


-PAS 


Pe on og 


. MMV 


i 1P 


. MMV 


.CA2 


. MMV 


~CA2 


~CA2 


A a 


.CA2 


. MMV 


-SLG 


~CA2 


-CA2 


.CA2 
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DCL 
Command 


SHOW DEFAULT 
SHOW LOGICALS 
(Show a specific 


1OGLCa.4) 


SHOW LOGICALS 
(Show all logicals) 


SHOW DEVICES 
SHOW MEMORY 

SHOW TASKS 

SHOW TASKS/ACTIVE 
SHOW TASKS/DYNAMIC 
SHOW TASKS/INSTALLED 
SHOW TASKS/LOGICAL_UNIT 
SHOW TERMINAL 

START 

START /UNBLOCK 
STOP/BLOCK 

TYPE 

UNLOAD 


UNLOCK 


Task/Utility 
Filename 


DBs 24PRODCU)LeET.TSkK 


LB: [ZZPRODCL]LCT.TSK 


LB: [ZZPRODCL]LNBDMP.TSK 


LB: [ZZPRODCL]CA2.TSK 
LB: [ZZPRODCL]RMD.TSK 
LB: {ZZPRODCL]CA2.TSK 
LB: [ZZPRODCL]CA2.TSK 
LB: [ZZPRODCL]RMD.TSK 
LB: [ZZPRODCL]CA2.TSK 
LB | ZZPRODCL /CA2.TSK 
LB: [ZZPRODCL]CA2.TSK 
LB: [ZZPRODCL]LCT.TSK 
LB: [ZZPRODCL]CATCH.TSK 
LB: [ZZPRODCL]CATCH.TSK 
LB: [ZZPRODCL]PIP.TSK 
LB: [ZZPRODCL]LCT.TSK 


LB? { 22PRODCL PIPsTSk 


Installed 
Task Name 


. MMV 


. MMV 


LG 


.CA2 


APPENDIX B 
ERROR MESSAGES 


This appendix lists two categories of error messages: general 
error messages and I/O error messages. 


NOTE 


Many system utilities issue error messages; these 
messages are explained elsewhere in the 
documentation set. 


B.1 GENERAL ERROR MESSAGES 


General error messages are common to many DCL commands. They can 
appear on your terminal screen preceded by a 3-letter code 
identifying the system component that detected the error. This 
can be the name of the utility (task) performing the command, or 
the command itself. This code appears here as yyy. 


Most of the general error messages with the word "expected" in 
them reprint the command on your terminal with a circumflex (° ) 
pointing to the error. Sometimes the circumflex points to _ the 


character just past the last successfully parsed command element. 
Many of the explanations refer to the Radix-50 character set. 
The Radix-50 characters are the uppercase alphabet, the numerals 
QO through 9, the dollar sign (3), and the period (.). 


yyy -- Allocation failure - no contiguous space 


Explanation: Not enough contiguous space is available on 
the output volume for the file being copied. 


User Action: Delete any files no longer required on the 
output volume and retry the command. 


yyy 


YYY 


‘ees 


‘ee, 


YYY 


YYY 
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-- Allocation failure on output file 
or 
-- Allocation failure -- no space available 


Explanation: Not enough space is availabl 
volume for the file being copied. 


User Action: Delete any files no longer 
output volume and retry the command. 


-~- A-Z expected 


Explanation: The command as typed included a 


character. 


e on the 


require 


d 


output 


on 


the 


nonalphabetic 


User Action: Check command for proper syntax and reenter. 


~- A-Z and/or 0-9 expected 


Explanation: The command as typed 


nonalphanumeric character. 


included 


a 


User Action: Check command for proper syntax and reenter. 


-- Bad error message 


Explanation: Some unusual condition has caused an error. 


User Action: Record the command that caused the 
other information on activity at your terminal at the time. 
Then call your DIGITAL Customer Support Center. 


-~- Bad use of wild cards in destination file name 


Explanation: A wildcard (*) was specified for 


file where it is not permitted. 


User Actions: Reenter the command with 
explicit file specification for the output 


-- Cannot find directory file 


oe & 


an 


ror 


and 


output 


a complete 


file. 


and 


Explanation: The command specified a directory not found on 


the current volume. 


User Action: Reenter the command after 
COrrect: directory and. correc: volume. 


checking 


for 


the 
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yyy -- Cannot find files 


Explanation: The file or files specified in the command are 
not in the designated directory. 


User Action: Check the file specification and reenter’ the 
command line. 


yyy -- Cannot rename from one device to another 


Explanation: The command attempted to rename a file across 
devices. 


User Action: Use the COPY command to move the file from one 
device to another and rename it. 


yVYY -- Cannot truncate this filetype 
Explanations The command attempted to truncate a file that 
cannot be truncated. Only files containing fixed-length, 


variable-length, or sequenced records can be truncated. 


User Action: Check to see if you have named the proper file 
and retry the command. 


yyy -- Close failure on input file 
Or 
yyy -- Close failure on output file 


Explanation: A file name in the command could not be 
properly closed. The file is locked by PIP. 


User Action: Use UNLOCK to unlock the file. Determine the 
cause of the error and correct it if you can. 


yyy -- Command function not unique 


Explanation: The command as typed did noc include 
sufficient characters to identify some command function. 


User Action: Retype command after checking proper syntax. 


yyy 


‘ees 


YYy 


yyy 


yy 


YYY 
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-- Command line incomplete 


Explanation: The command as typed is not 


command. 


a 


complete 


User Action: Retype command after checking proper syntax. 


-- Command syntax error 


Explanations The command did not conform to 


rules. 


User Action: Check command for proper’ syntax 


eee 


~- Conflicting qualifier 


the 


and 


syntax 


reenter 


Explanation: The command as typed included qualifiers that 
conflict with each other in their effect. 


User Action: Retype command after checking proper syntax. 


-- Contradictory qualifier 


Explanation: The command as typed included contradictory 
qualifiers, such as /DELETE and /NODELETE. 


User Action: Check for proper syntax and reenter command. 


-- Contradictory qualifier in key specification 


Explanation: The command included a contradictory qualifier 
in the key definition argument to the /KEY qualifier. 


User Action: Check command for proper syntax and reenter. 


-- Decimal number expected 


Explanation: The command included a number not 


format. 


User Action: Check command for proper syntax 


with a decimal point 


% 


) 


terminating the number. 


in 


and 


proper 


reenter 
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yyy -- Device invalid or not specified 


Explanation: The command specified an invalid device or no 
device at all when a device name is required. 


User Action: Check the devices on the system with SHOW 
DEVICES. Reenter command after checking for proper syntax. 
Determine the cause of the error and correct it if you can. 


yyy -- Device not in system 


Explanation: The command specified a device that is not in 
the current system. 


User Action: Check the devices on the system with SHOW 
DEVICES. Reenter command after checking for proper syntax. 


yyy -- Device not mounted/allocated 


Explanation: The command specified a device that is not 
properly mounted or allocated for the command to execute. 


User Action: Check the status of the device with SHOW 
DEVICES. Find the cause of the error and correct it if you 
can. 


yyy - Device not terminal 


Explanation: The command specified a device other than a 
terminal where a terminal device name is required. TI: is 
not an acceptable terminal device name in all contexts. 


User Action: Reenter the command after checking for proper 
syntax. 


yyy -- Directory write protected 


Explanation: The command attempted to remove an entry from 
a directory that is privileged or from a directory ona 
device that is write-protected. 


User Action: Determine the cause of the error and correct 
it if you can. You may need to enable write access through 
the device hardware or change the protection for _ the 
directory. 
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yVYy -- Error dispatching command. DSW = ‘n’ 


Explanation: An error occurred that was not explicitly 
handled by DCL or some invoked task. 


User Action: Look up the DSW error code in the P/OS System 
Reference Manual. Determine the cause of the error and 
COrrect 20-2 you -can. 


yyy -- Explicit output file name required 


Explanation: The command requires’ an explicit output 
filename. 


User Action: Reenter the command line in proper syntax and 
without wildcards. 


yyy -- Extraneous input 
Explanation: The command as typed included extraneous 
input: The circumflex (°~) points to the error or just past 


the last successfully parsed command element. 


User Action: Reenter the command line in proper syntax. 


yyy -- Failed to attach output device 
or 

yyy -- Failed to detach output device 
Explanation: An attempt to attach or detach a 
record-oriented output device, such as a terminal or line 


printer, failed. This error usually means the device is 
off-line or nonresident. 


User Actions Determine the cause of the error and correct 
Pt, eh You. Gan. 


yyy -- Failed to create output UFD 


Explanations The command failed to create an entry in a 
directory because the device was write-protected or because 
of a privilege violation. 


User Action: Determine the cause of the error and correct 
it if you can. You may need to enable write access through 
the device hardware or change the protection for the 
directory. 


‘ee 4 


yyy 


yyy 


yyy 


Ly 


eo 
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-- Failed to delete file 


or 


-- Failed to mark file for delete 


Explanation: The command attempted to 


file. 


User Action: Check for the proper 
default directory and reenter the command. 


-- Failed to enter new filename 


Explanation: The command 


exists in the directory, 


User Action: Check for proper syntax; 


-- Failed to find files 


specified 


file 


a 


Explanation: The command specified a fi 
could not be found as specified. 


User Action: Check for 


reenter the command. 


proper f 


-- Failed to get time parameters 


ile 


delete 


a 


per 


otected 


Specification and 


file that 
or the directory is protected. 


le or 


file 


already 


reenter command. 


s that 


Specifications and 


Explanations An internal system problem has occurred. 


User Action: Retry the 
record the command 


command. 


that 


caused 


EE 
the 


the error 


etrro-P 


and 


information on activity at your terminal at the time. 
call. your DIGITAL Customer Support Center. 


-- Failed to read attributes 


Explanation: The command specified a volume that is 
corrupted or protected against access. 


recurs, 
other 
Then 


either 


User Action: You may be able to correct the error by making 
your defaults the same as the device and directory of the 


file you wish to affect. 
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yyy -- Failed to remove directory entry 


Explanation: The command attempted to remove an entry from 
a directory that was either protected against access or ona 
write-protected device. 


User Action: Determine the cause of the error and correct 
it aif you can. You may need to enable write access through 
the device hardware or change the protection for the 
directory. 


yyy -- Failed to truncate file 


Explanation: The command specified a volume that 1s 
corrupted or is protected against access. 


User Actions You may be able to correct the error by making 
your defaults the same as the device and directory of the 
file you wish to affect. 


yyy -- Failed to write attributes 


Explanations The command specified a volume that is 
corrupted or is protected against access. 


User Action: You may be able to correct the error by making 
your defaults the same as the device and directory of the 
file you wish to affect. 


yyy -- Fatal I/O error 
Explanation: The command failed to execute because of some 
1/0’ error. This error can be caused by the unavailability 
of a device or of pool space, or by a device error. The 


device may be write-locked. 


User Action: Determine the cause of the error and correct 
Lot “Vou. ‘cam. 


yyy -- File is lost 


Explanation: PIP has removed a file from its directory, 
failed to delete it, and failed to restore the directory 


entry. 


User Action: Type @VERIFY to run the lost-file check to 
recover the filename. 


GENERAL ERROR MESSAGES 


yyy -- Filename or filetype not specified 
Explanation: The command as typed did not clearly specify a 
filename and file type where one or the other or both is 
required. This error can be caused if you do not leave a 
Space in front of a file specification that is a parameter. 


User Action: Retype command after checking for proper 
syntax. 


yyy -- File not locked 


Explanation: An UNLOCK command specified a file that is not 
locked. 


User Action: Check for the proper file specification and 
reenter the command. 


yyy -- File specification either invalid or not specified 
Explanation: The system could not read a file specification 
included in the command. This error often results from a 


typing mistake or typing the command in the wrong format. 


User Action: Check for proper syntax and reenter the 
command. 


yyy -- File specification list not available for RMS-11 


Explanation: A command to an RMS-11 utility included more 
than one input file specification. 


User Action: Check for proper syntax and reenter command. 
yyy -- File version number not specified 


Explanation: The command requires a file version number to 
be specified. 


User Action: Reenter command after checking for proper 


syntax. 
yyy -- Function not unique 
Explanation: The command as typed Gaivd not include 


sufficient characters to identify some function. 


User Action: Retype che command but include more 
characters. 


GENERAL ERROR MESSAGES 


yyy -- Get command line - Bad @ filename 


Explanations The command specified an illegal indirect 
command file. 


User Action: Check for proper file specification and 
reenter the command. 


yyy -- Illegal command 


Explanation: The command, which is the first word on _ the 
command line, is not part of DCL. 


User Action: Check command for proper syntax and reenter. 


yyy -- Illegal device 


Explanation: The command named a device in an illegal 
format or contained some other syntax error. 


User Action: Check command for proper syntax and _ reenter. 
Device names are two alphabetical characters followed by an 
octal number and a colon. 


yyy -- Illegal filespec 


Explanation: The command required a file specification that 
was not present. 


User Action: Check command for proper syntax and _ reenter. 
See Chapter 2 for a complete description of a file 


Specification. Perhaps some other command element is being 
parsed as a filespec. Use the prompting version. 


yyy -- Illegal or contradictory qualifier 


Explanation: One or more qualifiers to the command are in 
CONTE LLet:. Or are 1m error: 


User Action: Check command for proper syntax and reenter. 


yyy -- Illegal protection code 


Explanation: The command specified a protection code in an 
improper format. 


User Action: Check command for proper syntax and reenter. 


GENERAL ERROR MESSAGES 


yyy -- Illegal qualifier value 


Explanation: The command as typed included an improper 
argument to a qualifier. 


User Action: Check command for proper syntax and _ reenter. 
In DCL, an argument is preceded by a colon (:). 


yyy -- Illegal use of wildcard character 
Explanation: The command included a wildcard (* or %) in a 
file specification in a way that would result in 


unpredictable or inconsistent output. 


User Action: Check command for proper syntax and reenter. 
You may not be able to use the wildcard. 


yyy -- Illegal task name 


Explanation: The command named a task using a task name in 
an illegal format. 


User Action: Check command for proper syntax and reenter. 
Task names include as many as six Radix-50 characters. 


yyy -- Input device must be a directory device 
Explanation: The command as typed specified a device that 
is not a directory device, suchas. a printer. Directory 
devices are those on which FILES-11 volumes with directories 
can be mounted. 
User Action: Correct syntax and reenter command. 


yyy -- Input files have conflicting attributes 


Explanation: Warning message. The command operation 
completed, but the files named had conflicting attributes. 


User Actions: Use DIRECTORY/ATTRIBUTES to Find the 
attributes of all input and output files involved. 
Determine if the conflict causes any difficulty. 


yyy -- Invalid command function 


Explanation: The command as typed requested a function that 
is not valid for that command. 


User Action: Check command for proper syntax and reenter 
eae 
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yyy -- Invalid command parameter 
Explanation: The command as typed included a parameter that 
LS Ot ‘Valid, In DCL, a parameter is either entered in 


response to a prompt or preceded by a space. 


User Action: Check command for proper syntax and reenter. 


yyy -- Invalid file specification list 
Explanation: The command included a list of file 
Specifications in an invalid format. In general, file 


Specifications in lists should be separated by commas and, 
optionally, blanks. 


User Action: Retype command after checking proper syntax. 
VVY =~ Invalid file -specitication qualitier 


Explanation: The command included a qualifier to ae file 
Specification that was not valid. In DCL, a qualifier is 
preceded by a slash (/). 


User Action: Check for proper syntax and retype the 
command. 


yyy -- Invalid terminal specified 


Explanation: A command directed to a specific terminal 
named the terminal in an improper format. 


User Action: Check the name of the terminal using SHOW 
DEVICE and reenter the command with the proper format. 


yyy -- Invalid time or date 


Explanation: The command specified a clock or calendar 
f1eld, or beth, tncorrectly. 


User Action: Check for proper syntax and retype the 
command. 


yyy -- Invalid UIC specified 


or 


GENERAL ERROR MESSAGES 


yyY ~= Invalid directory specified 
Explanation: The command specified: 


® A named character containing a nonalphanumeric string or 
more than nine characters, or 


© A numbered directory containing 0 or a number that 
includes 8 or 9 or a number greater than 377 (octal). 


User Action: Retype command after checking for proper 


syntax. 

VVy =~= 17/0 SPror on: anput. file 
or 

YvVy => 170 error om output tile 


Explanation: One of the following conditions exists: 
@© The device is not on line. 
@® The device is not mounted. 
@ The hardware has failed. 
@ The output volume is full. 
@e The input file is corrupted. 


User Actions: Determine the cause of the error and correct 
It. if “yous can. 


yyy -- Key position size or number not specified 
Explanation: The command failed to include the size or 
number of a key position in the key definition argument to 
the /KEY qualifier. 
User Action: Check command for proper syntax and retype it. 


yyy -- Key specification out of sequence 


Explanation: The command included improper syntax in the 
key definition argument to the /KEY qualifier. 


User Action: Check command for proper syntax and reenter. 
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yyy -- More command parameters than permitted 


Explanation: The command as typed included too many 
parameters. 


User Action: Check command for proper syntax and reenter. 
yyy -- No such file 


Explanation: The command requested operations on ae file 
that does not exist. 


User Action: Make sure you have named the file properly. 
Check your defaults to be sure you are looking in the right 
directory on the right device. You may have made ae typing 
error. If the desired file is in fact not present, find out 
why it 1S not present and proceed accordingly. 

yyy -- Not a directory device 


Explanations A directory-oriented command named a device 
that does not have directories, such a line printer. 


User Action: If you can, reenter the command without 
Specifying a directory. 


yyy -- Numeral expected 
or 
yyy -- Numeral required 


Explanation: Command included nonnumeric characters in a 
position where numerals are required or expected. 


User Action: Check command for proper syntax and reenter. 
YyYy -- Octal number expected 


Explanation: The command included a number with an 8 or 9 
where an octal number was expected. 


User Action: Check command for proper syntax and reenter. 


GENERAL ERROR MESSAGES 


vyy -- Open failure on file 


Explanation: The system could not open a required file for 
some reason. 


User Action: Check the directory to be sure that the file 
is present, not locked, and in the proper format. If the 
file is locked, it may be corrupted or contain bad data. 
Determine the cause of the error and correct it if you can. 
Yyy -- Output device must be a directory device 
Explanation: The command as typed specified a device that 
1s not a directory device, such as a printer. Directory 
devices are those on which FILES-11 volumes with directories 
can be mounted. 
User Action: Correct syntax and reenter command. 
VVYY -- Primary key not specified 
Explanation: A command affecting an indexed file failed to 
include a primary key. In many such commands, you cannot 
Specify any action on an alternate key without first 
identifying the primary key. 
User Action: Check for proper syntax and reenter command. 


yY¥Y -- Qualifier inconsistent with compiler 


Explanation: A compiler command included a qualifier not 
acceptable by that compiler. 


User Action: Check the command for proper syntax and try it 
again. 


yyy -- Qualifier not available for this command format 


Explanation: The command included a qualifier that 1s 


invalid in the current context of the command. The context 
is usually determined by some other qualifier in _ the 
command. 


User Action: Reenter command after checking for proper 
syntax. 
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yyy -~ Qualifier not unique 
Explanation: The command as typed did not include 
sufficient characters to identify some qualifier. In DCL, 


qualifiers are preceded by a slash (/). 


User Action: Retype the command, but include more 
characters: 


yyy -- Qualifier value invalid here 
Explanation: The commands as typed included an 
inappropriate argument to a qualifier. In DCL, an argument 


LS usually preceded bya colon: (2). 
User Action: Check command for proper syntax and reenter. 
yyy -- Radix-50 expected 


Explanation: The command included a non-Radix-50 character 
where Radix-50 required. 


User Action: Reenter the command using proper syntax. The 
Radix-50 characters are the uppercase alphabet, the numbers 
0 through 9, the dollar sign ($), and the period (.). 


yyy -- Repeated command parameter 


Explanation: The command as typed included one parameter 
more than once. In DCL, a parameter is preceded by a blank 
Or "Prompc.: 


User Action: Retype command after checking for proper 
syntax. 


yyy -- Repeated key specification 
Explanation: The command as typed included the same _ key 
specification more than once in the key definition argument 


to the /KEY qualifier. 


User Action: Retype command after checking for proper 
syntax. 


GENERAL ERROR MESSAGES 


yyy -- Repeated keyword in key specification 
Explanation: The command as typed included the same keyword 
more than once in the key definition argument to the /KEY 
qualifier. 


User Action: Retype command after checking for proper 
syntax. 


VYyY -- Repeated qualifier 


Explanation: The command specified the same qualifier more 
than once. In DCL, a qualifier is preceded by a slash (/). 


User Action: Reenter command after checking the syntax to 
see if it is right. 


yyy -- Required parameter not specified 
Explanation: The command cannot execute without required 
parameters, such asa file specification or attribute. In 


DCL, a parameter is preceded by a blank or prompt. 


User Action: Retry the command, using the prompts. DCL 
prompts for all required parameters. 


yyy -- Required qualifier not specified 


Explanation: The command requires a qualifier that it does 


not. -1nclude. In DCL, a qualifier is preceded by a slash 
7) 
User Action: Check for proper syntax and reenter’ the 
command. 

yyy -- Required qualifier value not specified 


Explanation: A qualifier to the command requires that you 
state a numerical argument. In DCL, an argument is usually 
preceded by a colon (:). 


User Action: Retype command after checking for proper 
syntax. 


GENERAL ERROR MESSAGES 


yyy -- Required value not specified for position size or number 


Explanation: The command failed to include a required value 
in the key definition argument to the /INDEXED qualifier. 


User Action: Check command for proper syntax and reenter. 


VV¥VY -- Sorry; line too dong 
Explanation: DCL commands are translated for execution by a 
system tack or “Wea lity. This error is caused by a 
translated command line that the destination task cannot 
handle. 


User Action: Check command syntax to see if you are 
Specifying elements that can be defaulted. Check to see iff 
you can enter the command twice with different qualifiers 
instead of entering one command. 


VVy ~@ Sorry; low pool 


Explanation: The command could not execute because of 


insufficient space in the system pool (dynamic storage 
region). 

User Action: The pool is the Executive’s data base. iS 6) 
general, each task, including commands, uses a certain 


amount of pool. If the pool is full or badly fragmented, 
there may not be sufficient space for the command to 


execute. Usually, pool problems clear up spontaneously if 
you wait. 
Retry the command after an interval. You should not attempt 


to execute any other task, not even an ABORT, when the pool 
is low. The task also absorbs pool. 


yyy -- Sorry, task active 


Explanation: The command required some action that cannot 
be taken on an active task. 


User Action: Determine the cause of the error and correct 
it if you can. Check the task with the various SHOW TASK 
commands, or SHOW MEMORY. 
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yyy -- Sorry, task not installed 


Explanation: The command attempted to invoke a task that 
was not installed. 


User Action: Try running the task with a command in the RUN 
S form. Determine the cause of the error and correct it if 


you. Can; 

VVy.'?= DVNtax error 
Explanation: The command included some error in typing or 
Specification, such as a letter where a number should 
appear. 


User Action: Check for proper syntax and reenter command. 
Yvy -- Version must be explicit or "*" 

Explanation: The command syntax requires that the version 

number of the file must be specified explicitly or as a 


Wildcard ( * >). 


User Action: Reenter the command with the version number 
correctly expressed. 


yyy -- Wildcards not permitted 


Explanation: Command included a wildcard (* or %) in a 
context where it is not permitted. 


User Action: Check for proper syntax and reenter command. 
Vyy -- Zero value not valid for key size or number 


Explanation: The command included a zero value in the _ key 
definition argument to the /KEY qualifier. 


User Action: Check command for proper syntax and reenter. 


B.2 1/0 ERROR MESSAGES 


I/O error messages are returned as codes. Table B-1 lists P/OS 
I/O error codes. Only partial abbreviations (xxx) are listed; 
the complete abbreviation is IE.xxx. The octal number listed is 
the low-order byte of the complete value (2’s complement of the 
decimal number). 


1/O ERROR MESSAGES 


Table B-1: I/O Error Messages 


Abbre- ==ErPror “No.-- 
viation Decimal Octal Meaning 


. BAD -1 a0) Bad parameters 

ee -2 376 Invalid function code 

.DNR -3 375 Device not ready 

. VER -4 374 Parity error on device 

.ONP =5 373 Hardware option not present 

SPC -6 Cee! Invalid user buffer 

. DNA -7 371: Device not attached 

. DAA -8 370 Device already attached 

. DUN a) 3:6) Device not attachable 

. EOF -10 366 End-of-file detected 

. EOV -11 365 End-of-volume detected 

.WLK -12 364 Write attempted to locked unit 

. DAO -13 363 Data overrun 

» SRE -14 362 Send/receive failure 

. ABO -15 361 Request terminated 

PRI -16 360 Privilege violation 

eRSU -17 Chey) Shareable resource in use 

.OVR -18 356 Invalid overlay request 

eh Al’ -19 355 Odd byte count or virtual address 
. BLK -20 354 Logical Block Number too large 

. MOD -21 353 Invalid UDC module number 

. CON -22 352 UDC connect error 

. NOD =23 3.04. System dynamic memory 

.DFU -24 350 Device full 

.LFU -25 347 Index file full 

-NSF -26 346 No such file 

. LCK -27 325 Locked from read-write access 
.HFU -28 344 File header full 

.WAC -29 243 Accessed for write 

ECKS -30 342 File header checksum failure 
WAT -31 341 Attribute control list format error 
.RER ~32 340 File processor device read error 
.WER -33 bee a File processor device write error 
. ALN -~34 536 File already accessed on LUN 

- SNC -~35 B35) File ID, file number check 

eSOC -36 334 File ID, sequence number check 
.NLN -37 333 No file accessed on LUN 


Abbre- 
viation 


CLO 
-NBF 
. RBG 


-NBK 
~ ILL 


we LF 
-RAC 
- RAT 
2 RCN 
LCE 
-2DV 


~FEX 
-BDR 
- RNM 
.BDI 
sEOP 
. BNM 
. BDV 
. BBE 
. DUP 
~oTK 
Be i 3 a! 
-NFI 
-ISQ 
EOL 
.BVR 
. BHD 


~OFL 
mo OG 
~ONL 
. NNN 
NEW 
‘BLS 
. TMM 
.NDR 
.URJ 


~-Error 
Decimal 


-38 
-39 
-40 


-41 
-42 


-43 
-44 
-45 
-~46 
-47 
- 48 


~49 
250 
so 
=32 
eke) 
-54 
~55 
-56 
od 
-58 
9 
-60 
-61 
62 
-63 
~64 


“65 
-66 
=05) 
-68 
-69 
-70 
da 
-72 
Se eo! 
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No.-7- 
Octal 


322 
oa) 
330 


32] 
326 


329 
324 
223 
S22 
Sad 
320 


oa 
310 
its 
314 
513 
S12 
ole 
30 
307 
306 
305 
304 
303 
302 
3.04 
300 


277 
276 
213 
274 
213 
LHZ 
ea gil 
270 
20d 


Meaning 


File was not properly closed 
File buffer space unavailable 
Invalid record size 


File exceeds space allocated, no blocks 
Invalid operation on file 

descriptor block 

Bad record type 

Invalid record access bits set 

Invalid record attribute bits set 
Invalid record number-too large 
Internal consistency error 

Rename--two different devices 


Rename--a new filename already in use 
Bad directory syntax 

Cannot rename old file system 

Bad directory syntax 

File already open 

Bad filename 

Bad device name 

Bad block on device 

Enter-duplicate entry in directory 
Not enough stack space (FCS or FCP) 
Fatal hardware error on device 

File ID was not specified 

Invalid sequential operation 
End-of-tape detected 

Bad version number 

Bad file header 


Device off line 

Block check, CRC, or framing error 
Device on line 

No such node 

Path Lost. to partner 

Bad logical buffer 

Too many outstanding messages 

No dynamic space available 
Connection rejected by user 


Abbre- 
viation 


Pio fe 
-NNC 
~NNL 
.NLK 


me poh 
-AST 


. FLN 


- TES 
wes 
-ALC 
- ULK 
-WCK 


«CNR 


--Error 
Decimal 


-76 
oo a, 
=18 
Eo 


-80 
-80 


~81 


-82 
-83 
-84 
239 
-86 


=9'°6 
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No.-- 
Octal 


264 
Z63 
262 
261 


260 
260 


Zor 


256 
Piao ae) 
254 
203 
Zz 


240 


Meaning 


Bad tape format 

Not ANSI ‘'D’ format byte count 
Not a network LUN 

Task not linked to specified 
ICS/ICR interrupts 


Specified task not installed 
No AST specified in connect 


Device off line when off-line 
request issued 


Invalid escape sequence 
Partial escape sequence 
Allocation failure 
Unlock error 

Write check failure 


Connection rejected 


APPENDIX C 
SAMPLE EDT INITIALIZATION FILE 


The Edit command initializes EDT using a default EDT 
initialization file. The complete file specification for this 
initialization file. 1s; 


LB000:[1,2]EDTSYS.EDT 


You can edit this initialization file to include commands’ that 
are Similar to those found in the example in this appendix (refer 
to the EDT Quick Reference Guide for further information on 
creating EDT initialization files). 


You can maintain one or more EDT initialization files in 
directories other than [1,2]. However, you must use the /COM 
qualifier in the EDT command line to use any command file not 
round.in. the detault directory . 


A sample initialization file follows. 


SET SCREEN 79 ' Sets screen width to 79 characters. 


SET CURSOR 2:15 ! EDT will scroll file, if cursor is moved before line 
Ll 2 or-atter line.15., 

SET WRAP 70 ' Sets the maximum line length of n character 

positions ¢70 ai this example). As you enter 

! text, EDT will attempt to wrap a full word that 

!' extends beyond character position 70. 


SET NOTRUNCATE ! Displays lines that extend beyond the line width set 
! by SET SCREEN 79. 


SET TAB 3 | Sets. che first tab stop at -character posi ction -37 all 
' other tab stops are set at multiples of 8 after the 
i Ei Tst. Gab: Scop: 


DEFINE KEY GOLD 


DEFINE KEY GOLD 


DEFINE KEY CONTROL 


SET MODE CHANGE 


AS: “Eke Bei 

Defines the keystroke sequence GOLD + E 
as the EXIT command in Change mode. 

AG TK OUST ie” 


Defines the keystroke sequence GOLD + Q as 
the QUIT command (used only in Change mode). 


AS "4+DC ADV C UNDC C." 


This keystroke sequence 
reverses the position of two letters. 


Causes EDT to begin the editing session in 
Change mode. 


INDEX 


Abbreviated form of DCL commands, CANCEL, 3-14 
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RUN installed task, 3-152 
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SET DEFAULT, 3-156 

SET DEVICE, 3-157 

SET HOST, 3-159 
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SET PROTECTION/NODEFAULT, 3-166 
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SHOW DEFAULT, 3-177 
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Yevelopment of the application, 
ciel e 
Yevice and file manipulation, 1-1 
also see Chapter 3 
JIBOL, 3-53 
JIFFERENCES, 3-57 
Jifferences format, 5-7 
JIRECTORY, 3-61 
Jirectory validation, 14-4 
,DISABLE, 4-41 
JISMOUNT, 3-65 
MP, 6-1 


command format, 6-2 
error messages, 6-11 
examples, 6-8 
header dump, 6-10 
invoking, 6-2 
multiple format dump, 6-8 
record dump, 6-9 
Switches, 6-3 
DO 
command line terminator, 2-2 
Document conventions, v 
Document structure, iii 
DUMP, 3-66 


EDIT. 3271 
EDIT/EDT, 3-71 
see EDT 
EDIT/PROSE, 3-74 
EDIT/SLP, 3-75 
Editors 
text, 1-4 
EDT command file 
directory location, 3-7/1 
use with /COMMAND qualifier, 
3-71 7 
Effect of qualifier position in 
command line, 2-4 
-ENABLE, 4-42 
.END, 4-46 
Entry point table, 7-3 
.ERASE, 4-47 
Error 
detection by system, 2-9 
Error messages 
indirect, 4-95 
Errors 
DCL Command Line, 2-9 
.EXIT, 4-49 
EXIT, 3-78 
ExX1 
from PRO/Tool Kit, 2-10 
Expressions, 4-16, 4-18 


File Compare Utility, 5-1 

File contents determination, 13-8 

File contents validation, 13-8 

File ‘Dump Utility, 6=1 

File manipulation commands, 1-2 

File specifications, 2-13 

File Structure Verification 
Utility, 14-1 
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Files marked for delete, 14-9 
/FINAL qualifier 
with ASSIGN, 3-9 
with DEFINE, 3-46 
FIX, 3-79 
Foreground processing, 
.-FORM, 4-50 
FORMAT, 3-81 
Format 
PIP commands, 12-2 
Format of library files, 7-2 
Formats of CMP output files, 
FORTRAN, 3-82 
/FR, 14-5 
FREE command, 8-/7 
Functional groups 
DCL commands, 1-1 
Functions initiated by DCL 
commands, A-1 


Fis 


5-6 


general error messages, B-1 
.GOSUB, 4-56 


.GOTO, 4-57 


Header dump, 6-10 
HELP, 2-5, 3-88 
aS a separate command, 2-5 
while using a DCL command, 
Hyphen 
in command line, 


2-5 
2-8 
I/O error messages, B-19 
IF, 4-25, 4-58 
IPACT:: 4460 
IFDF, 4-61 
.IFDISABLED, 
.LFENABLED, 
LFF, 4-65 
-LFINS, 4-62 
.IFLOA, 4-64 
.1FNACT, 4-60 
.IFNDF, 4-61 
-LFNINS, 4-62 
.LFNLOA, 4-64 
LEE. 65 
-INC, 4-66 
Indirect 
sAoK, 
.ASKN, 
sASKS;, 
-BEGIN, 


4-63 
4-63 


4-28 

4-30 

4-33 
4-35 


Index-4 


INDEX 


information only messages, 


.CHAIN, 4-36 
.CLOSE, 4-37 
command files, 4-1 
command processor, 
.DATA, 4-38 

.DEC, 4-39 

define logical EOF, 
.DELAY, 4-40 
directive summary, 
.DISABLE, 4-41 
.ENABLE, 4-42 
-END, 4-46 
.ERASE, 4-47 
error messages, 
~EXIT, 4-49 
expressions, 
~FORM, 4-50 
sGOSUB, 4-56 
.GOTO, 4-57 
.IF, 4-25, 4-58 
.IFACT, 4-60 
-IFDF, 4-61 
.IFDISABLED, 
.LFENABLED, 
-IFF, 4-65 
.IFINS, 4-62 
.IFLOA, 4-64 
.LFNDF, 4-61 
.IFNINS, 4-62 
.IFNLOA, 4-64 
SEED: 20265 
.INC, 4-66 


4-2 


4-27 


4-4 


4-95 


4-16, 4-18 


4-63 
4-63 


4-94 
.LABEL, 4-67 
messages, 4-94 
numeric symbols, 
~ONERR, 4-68 
.OPEN, 4-69 
.OPENA, 4-70 
.OPENR, 4-71 
~.PARSE, 4-72 
».PAUSE, 4-73 
.READ, 4-74 
reserved symbols, 
.RETURN, 4-76 

RSX compatibilty, 
,oEID, 4= 79 
Souter: aa77 
sSETiy,; 4277 
.SETN, 4-78 
~.SETO, 4-79 


4-16 


4-19 


4-93 
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.SETS, 4-80 LB:[1,2]EDTSYS.EDT 
SHETTY; -A4= 77 see EDT use with /COMMAND 
special symbols, 4-9 qualifier 
logical, 4-9 LBR, 7-1 
numeric, 4-11 JEO4: F=L5 
String, 4-14 combining library functions, 
-STOP, 4-82 7-42 
string symbols, 4-18 compress switch, 7-15 
substitution format, 4-20 /CR, 7-16 
substrings, 4-18 create switch, 7-16 
Switches, 4-21 JDE, 7-18 
symbol substition, 4-19 default switch, 7-19 
symbols, 4-8 delete global switch, 7-21 
-TEST, 4-83 delete switch, 7-18 
MTESTDEVICE... 4285 JDF, 7-19 
-TESTFILE, 4-86 /DG, 7-21 
-TESTPARTITION, 4-87 entry point switch, 7-23 
-TESTSYSTEM, 4-88 entry point table, 7-3 
. TRANSLATE, 4-90 JEP, 7-23 
using directives, 4-24 error messages, 7-43, 7-44 
.WAIT, 4-91 /EX, 1-25 
.XOT, 4-92 extract switch, 7-25 
Indirect Command Processor fatal errors, 7-44 
refer to Chapter 4 file specifier defaults, 7-11 
use with PRO/Tool Kit DCL /FU, 7-29 
commands, 2-1 /IN, 7-26, 7-27 
Indirect Command Processor, 4-1 insert switch, 7-26, 7-27 
INITIALIZE, 3-89 invoking, 7-il 
Input file wildcards, 12-11 JLE, 7-29 
INSTALL, 3-91 /bl, 7-29 
Installation of application, i111 library file format, 7-2 
Intended audience, 111 library header, 7-2 
Interactive list switches, 7-29 
program development, 1-1 /MH, 7-30 
program execution and control, modify header switch, 7-30 
1-1 module header, 7-3 
Interactive use of PRO/Tool Kit module name table, 7-3 
DCL, 2-1 replace switch, 7-31, 7-37 
Invoking restrictions, 7<10 
CMP, 5-2 /RP, 7-31, 7-37 
CVT, 11-1 selective search switch, 7-39 
DMP, 6-2 Squeeze switch, 7-40 
LBR, 7-11 JSS, 1-39 
PAT, 13-2 Switches, 7-13 
PIP, 12-1 /SZ, 1-40 
RMD, 8-2 /LI, 14-6 
SUP eZ Librarian Utility Program, 7-1 
VFY, 14-1 LIBRARY, 3-93 
ZAP, 9-7 Library header, 7-2 
LIBRARY/COMPRESS, 3-94 


.LABEL, 4-67 LIBRARY/CREATE, 3-96 
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LIBRARY/DELETE, 3-99 
LIBRARY/EXTRACT, 3-100 
LIBRARY/INSERT, 3-101 
LIBRARY/LIST, 3-103 
LIBRARY/REMOVE, 3-105 
LIBRARY/REPLACE, 3-106 
LINK, 3-108 
LINK/C81, 3-123 
/LO, 14-6 
LOAD, 3-126 
Locations 
addressing 
in files, 
/LOG qualifier 


9-5 


INDEX 


errors in file contents, 13-15 
errors in file format, 13-15 
file contents determination, 
13-8 
File contents validation, 
file specification errors, 
13-11 
I/O errors, 13-13 
information messages, 
input file, 13-4 
internal software error, 
invoking, 13-2 
messages, 13-9 
module, 13-5, 


13-8 


13210 


13-16 


137] 


with PRINT/REMOTE, 3-142 object modules, 13-5 
Logical name translation, 2-15 overlaying lines, 13-5 
Lost block recovery, 14-10 storage allocation error, 13-17 
updates, 13-3 
MACRO, 3-127 updating object modules, 13-5 
MAIL, 3-135 Validation, 1326 
Manual objectives, i111 -PAUSE, 4-73 
Miscellaneous commands, 1-3 Peripheral Interchange Progran, 
Module name table, 7-3 12-1 
MOUNT, 3-136 PHONE, 3-140 
Multiple format dump, 6-8 PIP, L261 
command format, 12-2 
Nesting command files, 4-1 error codes, 12-23 
/NOWARNINGS qualifier error messages, 12-13 
with PRINT/REMOTE, 3-142 file specification fields, 12-3 
Numeric symbols, 4-16 input file wildcards, 12-11 
invoking, 12-1 
Object Module Patch Utility, 13-1 output file wildcards, 12-10 
Object modules, 13-5 specifying wildcards, 12-10 
.ONERR, 4-68 sSubswitches, 12-5, 12-9 
.OPEN, 4-69 Switches, 12-5, 12-8 
.OPENA, 4-70 PRINT, 3-141 
.OPENR, 4-71 PRINT/REMOTE, 3-142 
Output file wildcards, 12-10 PRIORITY command, 8-9 
Overlaying lines, 13-5 PRO/TK 
OWNER command, 8-9 Refer to PRO/Tool Kit 
PROYTOOL. Kitty. 1-4 
Parameters environment, i-1 
in DCL command line, 2-2 imtroauction,. t=] 
.PARSE, 4-72 Origins, 11 
PASCAL, 3-137 requirements to run, 1-1! 
PAT, 13-1 utilities description, 1-4 
adding subroutine, 13-7 PRO/ TOO: ‘Kit DCL 
applying updates, 13-3 Refer to PRO/Tool Kit Command 
command line errors, 13-10 Language 
command line format, 13-2 use with Indirect, 2-1 


correction file, 13-4 


PRO/Tool Kit DCL commands 
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alphabetical 
description of, 3-1 
Processing 
background 
use of ABORT command, 2-15 
foreground 
use of CTRL/C, 2-15 
Program development commmands, 
1-2 
Prompting, 2-2 
examples of, 2-2 
when invoking DCL, 2-2 
PURGE, 3-143 


Qualifier 
/SHOW, 3-55 
Qualifiers 
definition of, 2-3 


Radix, 11-2 
RATE command, 8-7, 8-9, 8-11 
/RC, 14-6 
~-READ, 4-74 
Record dump, 6-9 
REMOVE, 3-146 
RENAME, 3-147 
Replacing lines in file, 10-16 
Reserved symbols, 4-19 
Resource Monitoring Display, 8-1 
-RETURN, 4-76 
RETURN 
command line terminator, 2-2 
RMD, 8-1 
active task display, 8-8 
altering active task display, 
8-8 
altering memory display, 8-7 
altering task header display, 
8-10 
display pages, 8 
error messages, 
FREE command, 
help display, 
invoking, 8-2 
memory display, 8-4 
OWNER command, 8-9 
PRIORITY command, 8-9 
RATE command, 8-7, 8-9, 8-11 


CO © 
{ 


running on second terminal, 8-3 


setup pages, 8-1 
TASK command, 8-9, 8-11 


INDEX 


task header display, 8-9 
RSX 

compatibilty, 4-93 
RSX-11M-PLUS, i-1 
RUN installed task, 3-152 
RUN uninstalled task, 3-150 
Running RMD on second terminal, 

8-3 


/SESSION qualifier 
with ASSIGN, 3-9 
with DEFINE, 3-46 
Set and Show commands, 1-3 
SET DAYTIME, 3-155 
SET DEFAULT, 3-156 
SET DEVICE, 32157 
SET HOST, 3-159 
SET PRIORITY, 3-160 
SET PROTECTION, 3-161 
SET PROTECTION/DEFAULT, 3-164 
SET PROTECTION/NODEFAULT, 3-166 
SET TERMINAL, 3-167 
SET TIME, 3-155 
-SETD, 4-79 
goETt; 4297 
soEThL,. 42/7 
.SETN, 4-78 
VSETO.,. 4279 
SETS, 4580 
PSETT.. 4277 
SHOW ASSIGNMENTS, 3-172 
SHOW CLOCK_QUEUE, 3-173 
SHOW COMMON, 3-174 
SHOW DAYTIME, 3-176 
SHOW DEFAULT, 3-177 
SHOW DEVICES, 3-178 
SHOW LOGICALS, 3-179 
SHOW MEMORY, 3-180 
SHOW PROTECTION, 3-181 
/SHOW qualifier 
arguments to, 3-55 
SHOW TASK/DYNAMIC, 3-188 
SHOW TASK/LOGICAL_UNITS, 3-191 
SHOW TASKS/ACTIVE, 3-182 
SHOW TASKS/ACTIVE/DYNAMIC, 3-190 
SHOW TASKS/INSTALLED, 3-186 
SHOW TERMINAL, 3-192 
SHOW TIME, 3-176 
SLE 
see DCL Single Line Editor 
SLP, 10-1 
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adding lines to file, 10-12 
audit trail 
controlling, 10-19 
deleting, 10-23 
length, 10-20 
position, 10-20 
Suppressing, 10-22 
value, 10-21 
command input, 10-3 
command input format, 5-8 
controlling, 10-18 
controlling audit trail, 10=19 
creating source files with, 
Loe 1] 


deleting lines from file, 10-14 


edit commands, 10-6, 10-8 
error messages, 10-24 
file processing, 10-5 
information message, 10-24 
input files, 10-2 
interactive commands, 10-9 
Imvoking;. LO=2 
listing, 10-114 
listing file, 10-4 
messages, 10-24 
numbered listing, 10-11 
operators, 10-10 
output files, 10-2, 10-4 
replacing lines in file, 10-16 
source files, 10-11 
switches, 10-18 
through Indirect, 10-10 
updating source files, 10-11 
using, 10-6 
Source files, 10-11 
Source anguage Input Program, 
10-1 
SPAWN, 3-193 
Special logical symbols, 4-9 
Special numeric symbols, 4-11 
Special string symbols, 4-14 
Special symbols, 4-9 
Specifying wildcards, 12-10 
START, 3-194 
START/UNBLOCK, 3-195 
Status bits 
task, 3-174 
.-STOP, 4-82 
STOP/BLOCK, 3-196 
String symbols, 4-18 


INDEX 


structure of DCL command line, 
2-1 
SUBMIT/REMOTE, 3-197 


Substitution format control, 4-20 


Substrings, 4-18 
Summary of indirect directives, 
4-4 
Symbol value substitution, 4-19 
Symbols, 4-8 
/SOYSTEM qualifier 
with ASSIGN, 3-9 
with DEFINE, 3-46 


TASK command, 8-9, 8-11 
Task header display, 8-9 
Task Manipulation Commands, 1-2 
Task status bits, 3-174 
Task/File Patch Program, 9-1 
Terminal 

attaching in background mode, 

2-16 
JTEOL, 2263 
sTESTDEVICE, 4-85 
-TESTFILE, 4-86 
.TESTPARTITION, 4-87 
JTESTSYSTEM, -2-68 
. TRANSLATE, 4-90 
Translation of logical names, 
2-15 

/TRANSLATION_ATTRIBUTES 

with ASSIGN, 3-9 

with DEFINE, 3-46 
TYPE, 3-198 


UNLOAD, 3-201 
UNLOCK, 3-202 
Updating object modules, 13-5 
Updating source files, 10-11 
JUSER qualifier 
with ASSIGN, 3-9 
with DEFINE, 3-46 
Using indirect directives, 4-24 
Utilities 
form, 1-4 
frame, 1-4 
program development, 1-4 
URL 
invocatiom. of 
CMP, 5-2 
CVT, 11-1 
DMP, 6-2 
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LBR, 7-11 addressing modes, 9-5 
PAT, 13-2 arithmetic operators, 9-11 
PIP, 12-1 block number, 9-13 
RMD, 8-2 branch target location, 9-19 
SLP, 10-2 byte offset, 9-13 
VFY, 14-1 Changing location contents, 
ZAP, 9-7 9-16 | 
close command, 9-14 
Validation, 13-8 close location, 9-9 
Validity check, 14-3 . closing file locations, 9-17 
VAX/VMS, 1-1 command line, 9-8 
Verify utilaty commands, 9-9 
see VFY commands, general purpose, 9-20 
VFY, 14-1 current location symbol, 9-13 
command format, 14-2 equal sign command, 9-22 
deleting file marked for delete, error messages, 9-31 
14-10 examples, 9-24 
deletion of multiple-allocated generap purpose commands, 9-10 
blocks, 14-10 I- and D-space, 9-5 
directory validation, 14-4 internal registers, 9-10 
/DV, 14-4 K command, 9-21 
error messages, 14-11 ful, 9-3 
file error reporting, 14-7 list switch, 9-3 
files marked for delete, 14-9 location specifier, 9-12 
/FR, 14-5 multiuser task image, 9-4 
free switch, 14-5 O command, 9-22 
invoking, 14-1 offset location, 9-18 
ful, 14-6 open command, 9-14 
list switch, 14-6 open location, 9-9 
/LO, 14-6 opening file locations, 9-16 
lost block recovery, 14-10 opening preceding location, 
lost switch, 14-6 9-17 
mode of operation, 14-3 operating modes, 9-2 
/RC, 14-6 previous location, 9=19 
read check switch, 14-6 R command, 9-23 
Switches, 14-4 regular task image, 9-3 
validity check, 14-3 relocation bias, 9-5 
relocation register, 9-14 
.WAIT, 4-91 resident libraries, 9-4 
Wildcard, 2-13 RETURN key, 9-10 
Wildcards, 12-10 separators in command line, 
9-12 
.XQOT, 4-92 Switches, 9-2 
task image addressing, 9-/ 
ZAP, 9-1 termination of, 9-/7 
absolute addressing, 9-/7 througnm indrrect, 9-6 
absolute location, 9-18 V command, 9-23 
addressing Tocatione,;, 9-5 X command, 9-20 
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